Howard Tech Note

如何在 MySQL 中進行 insert if not exists

Fri, 07 Feb 2025 09:39:10 +0800

Howard Tech Note https://blog.idontwannarock.dev/2025/02/how_to_insert_if_not_exists_in_mysql/ -

相信很多 Developer 都會真心的幹譙懷疑為什麼 MySQL 經過這麼多年都沒有 PostgreSQL 的 INSERT … ON DUPLICATE KEY DO NOTHING 語法，偏偏這真的是一個很常會碰到的使用情境

所以接下來探討一些單一 SQL 語法方面可行的做法

準備

環境為 MySQL server 8.0.37

首先建立以下 table (只是為了情境驗證，合理性就先不計較)

drop table if exists test_user;
create table if not exists test_user (
 id int unsigned auto_increment primary key,
 user_id int unsigned not null,
 is_active boolean not null default 1,
 constraint uk_user_id_user unique (user_id)
) engine = innodb charset = utf8mb4 collate = utf8mb4_0900_ai_ci;

情境就是要在表中新增一筆 user 紀錄，如果該 user id 已經存在，就不做任何變更

每個情境測試前都會重新建立整個 table，以避免其他問題影響測試結果

取得 auto increment 數字前，可能需要 analyze table 以校正數據

`insert`

第一個方法就是直接 insert

mysql> insert into test_user (user_id) value (1);
Query OK, 1 row affected (0.01 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert into test_user (user_id) value (1);
ERROR 1062 (23000): Duplicate entry '1' for key 'test_user.uk_user_id_user'

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 3 |
+------------+----------------+
1 row in set (0.00 sec)

可以看到功能完全可以達成

但是有以下兩個問題

第二次以後的 insert 就會直接噴 duplicate key error
即使第二次實際上並沒有變更資料，auto increment 還是會 +1

因為 insert 實際上會先按照原有的 auto increment 準備一個新的 row，然後 auto increment 會 +1，接著在檢查到 duplicate key 後，直接拋 duplicate key error 並 reject statement 的執行，auto increment 並不會 rollback

如果這些問題可以處理或忽略，也不妨考慮這個方式，因為語意上比較明確，也可以讓 client 針對各種可能拋出的錯誤做不同的處理

但有時候在某些考量下，例如 Java 的 catch exception 有其 overhead，還是希望有不會 raise duplicate key error 的作法

`insert ignore`

如果不希望 raise duplicate key error，首先可以考慮 insert ignore

mysql> insert ignore into test_user (user_id) value (1);
Query OK, 1 row affected (0.01 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert ignore into test_user (user_id) value (1);
Query OK, 0 rows affected, 1 warning (0.00 sec)

mysql> show warnings;
+---------+------+---------------------------------------------------------+
| Level | Code | Message |
+---------+------+---------------------------------------------------------+
| Warning | 1062 | Duplicate entry '1' for key 'test_user.uk_user_id_user' |
+---------+------+---------------------------------------------------------+
1 row in set (0.00 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 3 |
+------------+----------------+
1 row in set (0.00 sec)

可以看到 insert ignore 的結果基本上與 insert 幾乎一樣，只差在原本第二次 insert 的時候會拋 duplicate key error，現在會被 ignore 關鍵字 suppress 成 duplicate key warning

這在使用上需要特別小心，因為 ignore 是真的會把所有 error 都忽略，可能會有些你意料之外的錯誤不應該忽略的也會被忽略

而且如果是 insert multiple rows 而且只有其中一些 row 有問題的狀況下，沒有問題的 rows 仍然會被成功 insert 不會整個 insert statement 被 reject，當然這個看狀況可能是缺點也有可能是優點

`replace`

不希望 raise duplicate key error 另一個選擇是採用 replace

mysql> replace into test_user (user_id) value (1);
Query OK, 1 row affected (0.01 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> replace into test_user (user_id) value (1);
Query OK, 2 rows affected (0.04 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 2 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 3 |
+------------+----------------+
1 row in set (0.00 sec)

可以看到 replace 跟 insert 也幾乎一樣，只差在第二次 replace 時是 2 rows affected 並且不會有 error 或 warning，並且在第二次 replace 後，該筆資料的 id 被變更為 2

這是因為 replace 實際上是先做 delete 再做 insert，因此被影響的是 2 個 row，因此也不會有 duplicate key error，因為實際 insert 的時候，原本會 duplicate 的 row 已經被刪掉了

replace 除了 id 會被改變、auto increment 還是會 kind of 浪費一個以外，最大的問題是如果 id 被其他 table 設為 foreign key 的時候，可能會產生你意料之外的結果，例如 cascade delete

`insert … on duplicate key update`

但如果我們既不想 id 被改變，也不希望 raise duplicate key error/warning 呢？

那可以先考慮 insert ... on duplicate key update 的做法

mysql> insert into test_user (user_id) value (1) as new on duplicate key update user_id = new.user_id;
Query OK, 1 row affected (0.05 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert into test_user (user_id) value (1) as new on duplicate key update user_id = new.user_id;
Query OK, 0 rows affected (0.00 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 3 |
+------------+----------------+
1 row in set (0.00 sec)

如此就達成既不會改變 id，也不會 raise duplicate key error/warning

但是仍然會造成 auto increment 被多 +1

另外，因為在 8.0.20 之後的 MySQL，values() 功能已 deprecated，所以改用 8.0.19 引入的 alias 語法以避免 warning

如果是 8.0.20 以前的版本，可以改採用 values() 寫法以避免 syntax error

insert into test_user (user_id) value (1) on duplicate key update user_id = values(user_id)

`insert … on duplicate key update id = id`

這個方式還有一個變種，網路流傳這樣寫，MySQL 會自動辨認如果有 duplicate key 要改作 update 也不會造成 auto increment +1，立刻就來做流言驗證！

mysql> insert into test_user (user_id) value (1) on duplicate key update id = id;
Query OK, 1 row affected (0.06 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert into test_user (user_id) value (1) on duplicate key update id = id;
Query OK, 0 rows affected (0.00 sec)

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 3 |
+------------+----------------+
1 row in set (0.00 sec)

結論不用多說了，MYTH BUSTED!

`insert … select … not exists`

如果我們既不想 raise duplicate key error/warning，也不想改變 id，還不想造成 auto increment waste 呢？(小孩子才做選擇，我全都要)

直接上驗證結果

mysql> insert into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists(select * from test_user where user_id = 1) limit 1;
Query OK, 1 row affected (0.06 sec)
Records: 1 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists(select * from test_user where user_id = 1) limit 1;
Query OK, 0 rows affected (0.00 sec)
Records: 0 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_schema = database() and table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

在正常情況下，這個方式差不多已經是最優解，既不會 raise duplicate key error/warning，也不改變 id，還不造成 auto increment 浪費

但這是正常情況下，當你有 high concurrent 的情況下就不見得如此了

簡單來說是因為 insert ... select 不是保證 atomic 的，select 跟 insert 是分段進行

如果剛好有相同 unique key 的兩次 insert … select … not exists 在幾乎相同的時間執行，可能還是會形成兩個 select 都認為沒有 duplicate row 而執行 insert，因而造成其中一個 statement 噴出 duplicate key error

`insert … select … not exists … on duplicate key`

mysql> insert into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists (select * from test_user where user_id = 1) limit 1 on duplicate key update id = id;
Query OK, 1 row affected (0.04 sec)
Records: 1 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists (select * from test_user where user_id = 1) limit 1 on duplicate key update id = id;
Query OK, 0 rows affected (0.00 sec)
Records: 0 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

這個方案算是結合 insert … select … not exists 跟 insert … on duplicate key，也就是當 insert … select … not exists 因為 concurrent 的關係準備要 insert 一個 duplicate row 的時候，就會改為執行 on duplicate key 的部分，而因為 insert … on duplicate key 是 atomic 的，所以這樣的操作不會拋出 duplicate key error/warning

在正常的情況下這個 statement 不會拋出 duplicate key error，id 不會變化，也不會造成 auto increment 浪費

但是在 concurrent 而形成其中一個 statement 會 insert duplicate row 的情況下，其實跟 insert … on duplicate key 的問題是相同的，就是有可能會造成 auto increment 浪費

`insert ignore … select … not exists`

mysql> insert ignore into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists (select * from test_user where user_id = 1) limit 1;
Query OK, 1 row affected (0.05 sec)
Records: 1 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.01 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

mysql> insert ignore into test_user (user_id) select temp.* from (select 1 as user_id) as temp where not exists (select * from test_user where user_id = 1) limit 1;
Query OK, 0 rows affected (0.01 sec)
Records: 0 Duplicates: 0 Warnings: 0

mysql> select * from test_user;
+----+---------+-----------+
| id | user_id | is_active |
+----+---------+-----------+
| 1 | 1 | 1 |
+----+---------+-----------+
1 row in set (0.00 sec)

mysql> select table_name, auto_increment from information_schema.tables where table_name = 'test_user';
+------------+----------------+
| TABLE_NAME | AUTO_INCREMENT |
+------------+----------------+
| test_user | 2 |
+------------+----------------+
1 row in set (0.00 sec)

這個方案是將 insert … select … not exists 加上 ingore 關鍵字，也就式在 concurrent 時，如果發生 duplicate 的狀況，duplicate key error 會被 suppress 成 duplicate key warning

在一般狀況下同樣不會拋出 duplicate key error，造成 id 改變，或造成 auto increment 浪費

但是在 concurrent 而形成其中一個 statement 會 insert duplicate row 的情況下，其實跟 insert ignore 的問題是相同的，就是有可能會造成 auto increment 浪費，而且萬一有其他應該被處理的 error 也會同樣被 suppress

Conclusion

直接做表格幫大家整理結論，MySQL 並沒有一個完美解決方案，只能根據狀況做取捨

statement	raise duplicate key error/warning	auto increment burn	id change
`insert`	error and reject	N	N
`insert ignore`	warning only	Y	N
`replace`	NA	Y	Y
`insert … on duplicate key update`	NA	Y	N
`insert … select ... not exists`	possible error and reject when concurrent	possible when concurrent	N
`insert … select ... not exists … on duplicate key update id = id`	NA	possible when concurrent	N
`insert ignore … select … not exists`	possible warning when concurrent	possible when concurrent	N

另外，本文僅針對各種單一 statement 的方法的硬限制作討論，並不涉及各 statement 速度、空間利用，也不比較 multiple statement 甚至牽涉 client 端的解決方案，而且僅針對預設設定做比較，不涉及改動 isolation level 或 MySQL server config

Reference

- https://blog.idontwannarock.dev/2025/02/how_to_insert_if_not_exists_in_mysql/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Percona XtraDB Cluster MySQL with Docker Compose

Wed, 16 Oct 2024 11:06:41 +0800

Howard Tech Note https://blog.idontwannarock.dev/2024/10/pxc_mysql_docker_compose/ -

因為公司 production 採用 Percona XtraDB Cluster 去架設 MySQL cluster，而 cluster mode 有很多預設的環境設定與非 cluster mode 的設定不同，例如 pxc_strict_mode 在 cluster mode 下，預設為 ENFORCING 或 MASTER，但非 cluster mode 的 pxc_strict_mode 預設為 DISABLE 而且還不能調整為 ENFORCING，導致有些 SQL 語法在 production 不支援

為了能夠在本機直接比照 production 環境配置去測試 SQL，所以研究如何快速在本機搭建出 Percona XtraDB Cluster cluster mode 的 MySQL

環境

WSL2 Ubuntu
Docker and Docker Compose installed and accessible from terminal

作法

先在同一個資料夾建立以下幾個文件

compose.yml

services:
 pxc-mysql:
 image: percona/percona-xtradb-cluster:8.0
 container_name: pxc-mysql
 restart: always
 privileged: true
 environment:
 - MYSQL_ROOT_PASSWORD=root
 - MYSQL_DATABASE=mmschat
 - CLUSTER_NAME=pxc-cluster
 - XTRABACKUP_PASSWORD=root
 ports:
 - "3306:3306"
 volumes:
 - "pxc-mysql-data:/var/lib/mysql"
 - "./cert:/cert"
 - "./conf:/etc/percona-xtradb-cluster.conf.d"
 - "./init.sql:/docker-entrypoint-initdb.d/init.sql"
volumes:
 pxc-mysql-data:

這份 docker compose 檔建立 pxc cluster mode 的 MySQL

conf/custom.cnf

在同位置建立 conf 資料夾，並在 conf 資料夾底下建立 custom.cnf

[mysqld]
ssl-ca = /cert/ca.pem
ssl-cert = /cert/server-cert.pem
ssl-key = /cert/server-key.pem
[client]
ssl-ca = /cert/ca.pem
ssl-cert = /cert/client-cert.pem
ssl-key = /cert/client-key.pem
[sst]
encrypt = 4
ssl-ca = /cert/ca.pem
ssl-cert = /cert/server-cert.pem
ssl-key = /cert/server-key.pem

用來配置 SSL 相關檔案位置

init.sql

GRANT ALL ON *.* TO 'root'@'%';
FLUSH PRIVILEGES;

讓 MySQL 啟動的時候，自動執行此 SQL 設定 root 帳號可以遠端存取

init.sh

#!/bin/bash
rm -rf ./cert
mkdir -m 777 -p ./cert
docker run --name pxc-cert --rm -v ./cert:/cert percona/percona-xtradb-cluster:8.0 mysql_ssl_rsa_setup -d /cert

這份 script 的步驟如下

清除 ./cert 資料夾以及其中的所有檔案
重新建立 ./cert 資料夾
利用 pxc docker image 內建的功能產生 SSL 相關檔案到 ./cert 資料夾

使用

第一次啟動前需要先執行 sh init.sh 以建立 SSL 檔案，之後就可以用 docker compose 指令建立、啟動、關閉或銷毀服務

啟動後可以進到 MySQL 使用以下 SQL 指令確認 cluster 狀態

show status like 'wsrep%';

然後檢查以下這幾項的設定，就可以確認 cluster 是否有建立成功

wsrep_local_state_comment: Synced
wsrep_cluster_size: 1
wsrep_cluster_status: Primary
wsrep_connected: ON
wsrep_ready: ON

另外可以使用以下 SQL 指令確認 pxc strict mode，若是 ENFORCING 或 MASTER 就是跟 production 集群相同

show variables like 'pxc_strict_mode';

Reference

- https://blog.idontwannarock.dev/2024/10/pxc_mysql_docker_compose/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

.gitattributes 引發的慘案

Wed, 22 May 2024 09:25:13 +0800

Howard Tech Note https://blog.idontwannarock.dev/2024/05/gitattributes_glowroot_error/ -

情況描述

最近在嘗試建立新專案的基礎專案架構，因為剛好看到常用的 APM 工具 Glowroot 0.14.2 版 release 開始支援 Java 21，讓我產生使用 multi-staged build + jlink 盡量縮小 image 大小，並且掛上 Glowroot 作為 Java Agent 來運行專案的念頭

因為以往已經將 Glowroot 使用在 Java 8, 11, 17 等版本的專案上，所以 Dockerfile 的基本架構已經確立，理論上只需要調整 base image 為 Java 21 應該就沒問題

FROM eclipse-temurin:21
ENV CONFIG_java_opts="-server -XX:+UseG1GC"
COPY extras/glowroot /extras/glowroot
COPY target/*jar app.jar
ENTRYPOINT exec java $CONFIG_java_opts -javaagent:/extras/glowroot/glowroot.jar -Dglowroot.collector.address=$CONFIG_glowroot_address -Dglowroot.agent.id=$CONFIG_app_name:: -jar /app.jar

其中

extras/glowroot 資料夾包含我直接從 Glowroot 0.14.2 Release 這邊下載後解壓縮出來的 glowroot.jar 檔，並且直接 commit 到 git 上
$CONFIG_java_opts、$CONFIG_glowroot_address 及 $CONFIG_app_name 都是定義在 K8S config map 中的變數，會在 K8S 運行這個 image 的時候從 pod 的環境變數取得

這樣的 Dockerfile 產出的 image 大約是 520MB，app.jar 檔大約 65MB，所以代表 image 的其他部分就有 455MB，其實有點大

如果我專案複雜一點可能光 app.jar 就會來到 4-500MB，那 image 甚至可能會將近 1GB，這樣在 CICD 頻繁的情況下對於 image 傳輸的壓力太大，而且 K8S rolling start pod 的速度也會很慢，所以才要盡量改成 multi-staged build 來縮小 image 大小

另外因為這套寫法已經在公司太多專案上運行了，所以我並沒有特別測試，就直接開始調整為 multi-staged build + jlink

FROM eclipse-temurin:21 AS jre-build
WORKDIR /app
COPY target/*.jar app.jar
# Analyze dependent modules of the app
RUN jar xf app.jar
RUN jdeps \
 --ignore-missing-deps \
 --print-module-deps \
 --multi-release 21 \
 --recursive \
 --class-path 'BOOT-INF/lib/*' \
 app.jar > modules.info
# Create a custom Java runtime
RUN $JAVA_HOME/bin/jlink \
 --add-modules $(cat modules.info) \
 --strip-debug \
 --no-man-pages \
 --no-header-files \
 --compress=0 \
 --output /javaruntime
# Define base image
FROM debian:stable-slim
ENV JAVA_HOME=/opt/java/openjdk
ENV PATH "${JAVA_HOME}/bin:${PATH}"
COPY --from=jre-build /javaruntime $JAVA_HOME
# Continue with app deployment
ENV CONFIG_java_opts="-server -XX:+UseG1GC"
COPY extras/glowroot /extras/glowroot
COPY target/*.jar app.jar
ENTRYPOINT exec java $CONFIG_java_opts -javaagent:/extras/glowroot/glowroot.jar -Dglowroot.collector.address=$CONFIG_glowroot_address -Dglowroot.agent.id=$CONFIG_app_name:: -jar /app.jar

這邊 app.jar 檔一樣大約 65MB，debian:stable-slim image 本身大約 75MB，而我最終產出的 image 大約 252MB，也就是說 jlink 產出的 JRE 大約 112MB 而已 (原生的 Java 21 JRE 約 143MB)，這代表除去 app.jar 檔以外，image 本身只有 187MB，相較於前一份 Dockerfile 產出的 455MB，大幅縮減了約 288MB

但是當我很開心的運行這個 image 的時候，卻碰到以下的錯誤訊息，導致程式完全無法運行

Error occurred during initialization of VM
agent library failed Agent_OnLoad: instrument
Error opening zip file or JAR manifest missing : /extras/glowroot/glowroot.jar

問題原因

我整個矇，因為 Glowroot 0.14.2 這版 release 已經出了一個多月，如果 jar 檔有問題，應該很多人都會碰到才對，而且搜尋了一下，還真沒有人開 issue，表示真的沒有其他人碰到這個問題，我只好反求諸己

權限問題？

我一開始的思路是權限問題，因為 stackoverflow 上很多碰到 Error opening zip file or JAR manifest missing 錯誤訊息的關鍵都是 jar 檔是否存在以及 jar 檔權限問題

首先 image 裡面 glowroot.jar 檔肯定是存在的，所以我開始查是不是權限問題，這裡我直接把 Dockerfile 精簡做測試

FROM eclipse-temurin:21
COPY target/*jar app.jar
ENTRYPOINT exec java -jar /app.jar

這樣運行完全沒有問題

於是簡單加上 Glowroot

FROM eclipse-temurin:21
COPY extras/glowroot /extras/glowroot
COPY target/*jar app.jar
ENTRYPOINT exec java -javaagent:/extras/glowroot/glowroot.jar -Dglowroot.collector.address=$CONFIG_glowroot_address -Dglowroot.agent.id=$CONFIG_app_name:: -jar /app.jar

很抱歉，立刻就報 Error opening zip file or JAR manifest missing 錯誤

這就很奇怪了，這邊 glowroot.jar 複製進 image 的方式跟 app.jar 一模一樣，app.jar 可以執行，沒有道理 glowroot.jar 會不行才對呀？

挖賽，光在這邊我就卡關了兩天，一直查 Dockerfile 權限問題想找出兩個 jar 檔的差異

直到我看到某一篇解答 Error opening zip file or JAR manifest missing 錯誤的時候提到

除了檢查 jar 檔是否存在及權限以外，也要檢查 jar 檔本身是否毀損

Jar 檔毀損？

我原本認為我是直接從官方 URL 下載下來的 jar 檔不可能有問題，但死馬當作活馬醫，於是我將 Dockerfile 改成每次都重新抓 Glowroot 的 jar 檔下來試試看

FROM eclipse-temurin:21
RUN apt-get update && apt-get install unzip
ADD https://github.com/glowroot/glowroot/releases/download/v0.14.2/glowroot-0.14.2-dist.zip /tmp/glowroot.zip
RUN mkdir /extras && unzip /tmp/glowroot.zip -d /extras
COPY target/*jar app.jar
ENTRYPOINT exec java -javaagent:/extras/glowroot/glowroot.jar -Dglowroot.collector.address=$CONFIG_glowroot_address -Dglowroot.agent.id=$CONFIG_app_name:: -jar /app.jar

這樣還真的就可以運行了！！！

看來是我 commit 上去的 glowroot.jar 檔真的是有問題，但我是從同一個 URL 下載下來的，怎麼可能有什麼問題呢？

`.gitattributes` 4 ni？！

於是我回到專案本身去查有沒有哪裡有可能動到 jar 檔，最後還真的讓我想到可能的兇手：.gitattributes

.gitattributes 檔是用來方便 Git 幫我們管理文件的屬性，Git 會在檔案在 repository, staging area 跟 working area 間轉換時，依照 .gitattributes 的設定調整對應的檔案，常用於統一設定檔案的換行符號

例如我的專案當中的 .gitattributes 如下

* text=auto

* text eol=lf
*.java text eol=lf
*.xml text eol=lf
*.md text eol=lf
*.yml text eol=lf
*.yaml text eol=lf

就我的理解，除了從第三行開始特別設定的檔案類型以外，Git 會先自己判斷檔案類型是 text 或 binary，如果是 text 類型的檔案，就會自動設定檔案的 eol(end-of-line) 為 lf

而一般人應該很自然地就會認為 jar 檔會被判斷為 binary 類型而不會受到影響

BUT，就是這個 BUT

我的第三行就設定了所有檔案都預設為 text…

而且 Git 在自動判斷檔案是 text 或 binary 的時候是採用 heuristics 的方式，所以就算讓 Git 自行判斷也不能保證絕對正確

而在我的情況，以往的 glowroot.jar 被視為 binary 檔因此沒有被改動，而這次卻被視為 text 類型的檔案，因此被 Git 改動而毀損

解決辦法

知道問題後就簡單了，在 .gitattributes 當中註明 jar 檔不是 text 檔如下

* text=auto

* text eol=lf
*.java text eol=lf
*.xml text eol=lf
*.md text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
*.jar -text

所以剛好藉此機會提醒自己，往後設定這種會變動到檔案的部分都要特別注意，在 .gitattributes 的部分，最好將所有會被 commit 的檔案類型都列出來，以避免 Git 判斷檔案類型會有出乎意料之外的問題

後記

我在查資料的時候，還找到 gitattributes 這個 repo，裡面紀錄了各種 .gitattributes 的樣板，裡面就有 Java 的版本，裡面就有特別將 *.jar 設定為 binary

還有這個網頁版的 .gitattributes 產生器，類似 gitignore.io 的用法，輸入語系就可以依照樣板產出對應的 .gitattributes 檔

Reference

- https://blog.idontwannarock.dev/2024/05/gitattributes_glowroot_error/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Java Time 保存到 MySQL DATETIME 時區問題

Wed, 27 Dec 2023 09:26:23 +0800

Howard Tech Note https://blog.idontwannarock.dev/2023/12/java_time_mapping_mysql_datetime_timezone/ -

最近開發遇到一個對我的系統需求來說很合適，但我感覺不合理的狀況

目前有 Spring Boot 系統在 JPA 是用 OffsetDateTime 在 Entity 中對應 MySQL 表中的 DATETIME 欄位，JVM 時區以及 MySQL 的系統時區都是 +8，沒有特別在任何地方進行時區設定，也就是所有地方應該都是預設設定

然而當 OffsetDateTime 保存到 DATETIME 當中時，卻會被自動轉換成 UTC 時區的時間保存，並且之後再用 JPA 重新取出後，OffsetDateTime 也依然是 UTC 時區

這就讓人感覺很奇怪了，感覺要馬就應該是 MySQL DATETIME 保存時用 JVM 跟 MySQL 相同的系統 +8 時區時間保存，取出也是 +8 時間；要馬就是保存時會轉成 UTC，但取出應該會自動轉換回 JVM 的 +8 才合理，畢竟 DATETIME 欄位資料格式不保存時區資訊，所以要馬就是完全不轉換，要馬就是會依照某種機制保存時用 UTC，但使用時會自動轉換成 JVM 時區之類的模式才對

雖然我原本就希望在系統中盡量都使用 UTC 時區而不要隨著 MySQL/JVM 時區變動以避免造成資料錯誤的問題，但機制不如預期就應該要弄清楚，免得其實是有什麼未知的狀況造成日後踩到坑

Pre-requisite

首先要先說明這篇文章的研究都是基於下列版本，不同的版本「可能」會有不同的行為，請查詢官網文件或自行測試

Spring Boot Data JPA 3.1.4
Hibernate 6.2.9.Final
MySQL JDBC Driver 8.0.33
MySQL server 8.0.33

資料類型選擇的考量

首先說明為什麼要選擇用 OffsetDateTime 對應 MySQL DATETIME 的考量

在 MySQL 當中可以同時保存日期及時間的格式只有 TIMESTAMP 及 DATETIME 兩種，其中 TIMESTAMP 資料格式只支援到 2038-01-19 03:14:07 UTC，而 DATETIME 格式可以支援到 9999-12-31 23:59:59

MySQL 因為用 signed 32-bit integer 來保存 TIMESTAMP 資料格式包含秒以上的資料，因此最多只能記錄到從 1970-01-01 00:00:01 UTC 開始後的 2147483647 秒，也就是 2038-01-19 03:14:07 UTC，超過一秒就會 stackoverflow；而 DATETIME 則採用完全不同的保存策略，所以可以支援到 9999-12-31 23:59:59

另外 TIMESTAMP 資料格式可能不見得適合在高併發的情況下使用，因為在 MySQL 官方文件的「5.1.15 MySQL Server Time Zone Support#Time Zone Variables」中有以下這段

Note

If set to SYSTEM, every MySQL function call that requires a time zone calculation makes a system library call to determine the current system time zone. This call may be protected by a global mutex, resulting in contention.

這段是在說 MySQL 系統的 time_zone 變數如果是預設的 SYSTEM，在每次需要做時區運算的時候，MySQL 系統就會取得全域鎖 (global mutex) 來做資料正確性的確保，導致鎖爭用 (lock contention)

而因為 TIMESTAMP 的時區自動轉換功能雖然能確保時間時區的正確性，卻容易導致每次存取都需要做時區轉換運算，進而導致鎖爭用發生，而對效能有影響

但另一方面來說，雖然 DATETIME 並不記錄時區而避免鎖爭用的問題，但卻相對容易衍生時區相關的問題

因為我的系統流量不小，加上不想在未來面對資料搬遷的問題，所以才選擇 DATETIME

而說到在 Java 這邊，因為舊的 java.sql.Timestamp 等時間相關的類別有許多問題，所以從 Java 8 開始推出了 java.time 系列的類別來處理時間相關的資料

當遇到要處理帶時區的時間時，比較常用到的類別就是 Instant 及 OffsetDateTime，而 Hibernate 官方文件中「2.2.48. Handling temporal data」有列出帶時區時間支援的類別只有 java.time.OffsetDateTime 及 java.time.ZonedDateTime 這兩個

而因為我的系統並沒有需要針對不同地方的時間做運算的需求，尤其是不需要計算日光節約時間，而只需要用 UTC 計算即可，所以才選用 OffsetDateTime

談完選用資料型態的考量後，就開始研究時區轉換的機制吧

時區轉換機制

在研究時區轉換機制之前，要先了解 JPA 是怎麼跟 MySQL 互動的

首先 Spring Boot Data JPA 是 Spring Boot 實作方便整合到 Spring Boot 系統並且符合 JPA 規範的介面，主要機制還是圍繞在操作預設使用的 Hibernate 實作，而 Hibernate 這個 ORM 則會透過內部機制去操作 JDBC Driver 最終跟 MySQL server 進行互動

在這個流程中，MySQL DATETIME 並不保存時區也不對保存的時間進行時區轉換，而 Spring Boot Data JPA 只是介接符合 JPA 實作的 ORM 框架以及 Spring Boot 系統，所以時區轉換的機制比較大的可能發生在 Hibernate 或 MySQL JDBC Driver 這兩者當中

MySQL JDBC Driver 的時區轉換

這邊我首先懷疑的是 JDBC Driver，因為 MySQL 的官網上很容易就能找到這份文件「6.6.1 Preserving Time Instants」有以下說明

The situation is less straightforward with the DATETIME data type: it does not represent an instant and, when no time zone offset is specified, there is no time zone conversion for DATETIME values, so they are stored and retrieved as they are. However, with a specified time zone offset, the input value is converted to the session time zone before it is stored; the result is that, when retrieved in a different session with a different time zone offset as the specified one, the DATETIME value becomes different from the original input value.

也就是說 DATETIME 資料格式不會做時區轉換，所以怎麼保存就怎麼取出來；但是如果保存的時候有帶上時區，會先將時間轉換成 session timezone 後再保存，因此當取出時，是在不同 timezone 的 session 中，取得的值會跟原先保存的原始值不同

MySQL 依照 session timezone 轉換時區的效果可以參考官網這份文件「9.1.3 Date and Time Literals」

這聽起來好像有可能符合我遇到的狀況，所以問題就在於 session timezone 是怎麼決定的

MySQL server timezone 的設定可以在這份文件「5.1.15 MySQL Server Time Zone Support」，但在使用 ORM 的時候這裡面提到的方式都不是合適的方法，因為其中要不是全域設定就是要額外下 sql 去變動，而且我也沒有做任何類似的設定

另外還有一種方式就是在 JDBC Driver connection url 上加上設定參數去調整連線的 timezone，如這份文件「6.3.11 Datetime types processing」說的 connectionTimeZone 及 forceConnectionTimeZoneToSession 參數也可以調整 session timezone，但是我也沒有做這個設定

這邊我透過 select @@system_time_zone, @@time_zone, @@global.time_zone, @@session.time_zone; 實際去查 timezone 的結果如下

@@system_time_zone	@@time_zone	@@global.time_zone	@@session.time_zone
CST	SYSTEM	SYSTEM	SYSTEM

可以看到基本上全部 timezone 都是比照 SYSTEM 也就是 MySQL 的系統時區 CST(+8)

那就很奇怪了，因為按照前面文件描述，DATETIME 欄位型態在面對插入的時間帶有時區的時候會按照 session timezone 來轉換時區後保存，但我面對的 session timezone 明明就是 +8，它到底是怎麼保存成 UTC 的呢？

Hibernate 的時區轉換

於是我們轉向另外一個嫌疑人 Hibernate，Hibernate 到底是怎麼做時區轉換的呢？或者說有沒有做時區轉換呢？

首先就是 Hibernate 有提供一個參數 hibernate.jdbc.time_zone 可以設定，這會讓 Hibernate 在將時間傳送到 DB 之前就先將時區轉換成參數設定的時區，取出來的時候也是會將時間轉回參數設定的時區

如果我設定這個參數為 UTC 的話，其行為就與我觀測到的相同，但是我並沒有設定這個參數，而這個參數的預設值是 JVM 時區，所以看來應該還有別的機制在作用

JDBC 4.2 時間格式規範

在講到 Hibernate 另外一個機制之前，要先提一下 JDBC 4.2 對於時間的規範

JDBC 4.2 新增了 JDBCType，其中對於時間資料規範了以下四種類型

DATE: 代表日期，保存年月日
TIME: 代表時間，保存時分秒
TIMESATMP: 代表日期及時間，保存年月日時分秒加上奈秒 (nanosecond)
TIMESTAMP_WITH_TIMEZONE: 代表日期及時間以及時區，保存年月日時分秒加上奈秒 (nanosecond) 以及時區 id 或 offset

MySQL JDBC Driver 時間格式支援

但是就如我們所知道的，MySQL 對於保存完整日期及時間的資料格式只有兩種，TIMESTAMP 及 DATETIME

其中 TIMESATMP 會把所有時間轉成 UTC 後再保存成 unix timestamp，而我們也知道 DATETIME 則是不保存時區的，所以 MySQL JDBC Driver 實際上是不支援 TIMESTAMP_WITH_TIMEZONE 這個 jdbc type 的，它實際上都會先處理好時間的時區後，再用 TIMESTAMP 這個 jdbc type 來傳送時間資料

至於 driver 內部怎麼處理時區，我們前面一段也已經講過，並不如我觀測到的狀況，所以現在才會要來看 Hibernate 是怎麼處理這個問題

Hibernate 5 的 normalization

但畢竟 Hibernate 還是要透過 JDBC Driver 才能真正跟 DB 互動，所以針對 MySQL JDBC Driver 不支援 TIMESTAMP_WITH_TIMEZONE 的問題，從 Hibernate 5 開始採取了一種策略，就是先將帶有時區資訊的時間先 normalize 成沒有時區的時間後再保存，normalize 的過程其實就是會將時間轉換成 JVM 的時區，而取出來的無時區時間再加上 JVM 時區做還原

例如今天 JVM 時區為 +8，而你要將時間為 2023-12-25 11:30:00+6 的 OffsetDateTime 保存起來，Hibernate 5 會先將 2023-12-25 11:30:00+6 轉換成 JVM 的時區並去掉時區資訊，也就是變成 2023-12-25 13:30:00 後再保存起來；而取出來後的 2023-12-25 13:30:00 則會直接加上 JVM 的時區 +8 後還原成時間為 2023-12-25 13:30:00+8 的 OffsetDateTime

採取這樣的機制的確可以避開 MySQL JDBC Driver 不支援 TIMESTAMP_WITH_TIMEZONE 的問題，但除非符合以下三個條件，否則時區資訊還是有可能會混亂

不使用有日光節約 (daylight saving) 的時區
所有 JVM instance 的時區都一致
永遠不會改變時區

Hibernate 6 的 `TimeZoneStorageType` 設定

這三個條件其實某種程度上是很嚴苛的，畢竟仍然有很多地區在使用日光節約時間，所以 Hibernate 6 就提出更進階的設定，讓使用者可以自己決定要如何將帶時區的時間 mapping 到資料庫的無時區時間資料欄位上

這裡我們可以直接參考 org.hibernate.annotations.TimeZoneStorageType 這個 enum，其中提供了六種設定選項

NATIVE
NORMALIZE
NORMALIZE_UTC
COLUMN
AUTO
DEFAULT

首先看名稱就知道是預設值的 DEFAULT，而 DEFAULT 到底是採取怎樣的策略呢？這邊我們可以直接參考 DEFAULT 的說明

Stores the time zone either with NATIVE if Dialect.getTimeZoneSupport() is org.hibernate.dialect.TimeZoneSupport.NATIVE, otherwise uses the NORMALIZE_UTC strategy.

簡單來說就是除非有特別設定，預設就是 NORMALIZE_UTC

那 NORMALIZE_UTC 又是怎麼運作呢？這邊先講 NORMALIZE 是怎麼運作的

NORMALIZE 的機制基本上就跟 Hibernate 5 的處理方式一樣，只差在可以透過 hibernate.jdbc.time_zone 這個參數設定 normalize 過程中要轉換的時區，也就是將帶時區時間轉換成無時區時間時，如果沒有設定 hibernate.jdbc.time_zone 則一樣轉成 JVM 時區；若是有設定 hibernate.jdbc.time_zone 就轉成 hibernate.jdbc.time_zone 設定的時區；反過來要將無時區時間轉回帶時區時間的時候，沒有設定 hibernate.jdbc.time_zone 就一樣直接帶上 JVM 時區，若是有設定則直接帶上 hibernate.jdbc.time_zone 設定的時區

這就是設定 hibernate.jdbc.time_zone 這個參數後的實際運作機制，如果使用 Spring Boot Data JPA 則是設定 spring.jpa.properties.hibernate.jdbc.time_zone

但這樣的機制仍然不能避免處理日光節約時間以及換時區的問題

所以就有 NORMALIZE_UTC 的出現，其實機制跟 NORMALIZE 非常相似，只差在它會強制將帶時區時間轉成 UTC 時間後再去掉時區資訊，轉回來的時候同樣也是直接將無時區資訊加上 UTC 時區

而因為任何時間在保存的時候都是保存成 UTC 的時間，取出來的時候也是一律轉換成 UTC 時間，所以就解決了日光節約時間以及換時區的問題

注意 NORMALIZE_UTC 直到 Hibernate 6.0.1.Final 才修正成為以上機制，並且直到 Hibernate 6.2+ 後才成為預設處理 database 不支援帶時區時間的機制

至此，這個機制的描述已經完全符合我觀測到的現象，但是盡信書不如無書，這邊還是要寫個測試來驗證一下

測試

首先建立測試的 schema 如下

create table dt
(
 id bigint auto_increment primary key,
 timestamp timestamp(3) not null,
 datetime datetime(3) not null
);

設定 Entity 如下

import jakarta.persistence.*;
import org.hibernate.annotations.CreationTimestamp;

import java.time.OffsetDateTime;

@Entity
@Table(name = "dt")
public class DtEntity {

 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long id;

 @CreationTimestamp
 private OffsetDateTime timestamp;

 @CreationTimestamp
 private OffsetDateTime datetime;

 // getter, setter omitted...
}

Repository

import com.example.lab.spring.boot.jpa.persistent.data.DtEntity;
import org.springframework.data.jpa.repository.JpaRepository;

public interface DtRepository extends JpaRepository<DtEntity, Long> {
}

然後透過正常的 JPA save() 方式新增記錄

var newDt = new DtEntity();
dtRepository.save(newDt);

也透過正常的 JPA findById() 方式取得資料

dtRepository.findById(id).ifPresent(dt -> System.out.println(dt));

我在執行的時候 JVM 跟 MySQL 的時區都是 +8，但這邊印出取得的資料確定是 UTC 時間如下

DtEntity(id=1, timestamp=2023-12-25T03:30:27.660Z, datetime=2023-12-25T03:30:27.660Z)

但我們想更進一步確定運作得是我們前面提到的機制，所以要在 application.properties 中再加上以下 log 設定

logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type=TRACE
logging.level.org.hibernate.orm.jdbc.bind=DEBUG
logging.level.org.hibernate.orm.results=DEBUG
logging.level.org.hibernate.resource.jdbc.internal.ResourceRegistryStandardImpl=TRACE

於是我們可以在 console 中看到以下這行 log 可以證實在 Hibernate 這層處理的時候就已經將時間轉換成 UTC 時間並轉成字串做 insert

2023-12-25T11:31:52.418+08:00 TRACE 29184 --- [nio-8080-exec-1] o.h.r.j.i.ResourceRegistryStandardImpl : Releasing statement [HikariProxyPreparedStatement@1053261670 wrapping com.mysql.cj.jdbc.ClientPreparedStatement: insert into dt (datetime,timestamp) values ('2023-12-25 03:31:52.399456','2023-12-25 03:31:52.399456')]

另外還可以看到以下幾行 log，此處即可證明 Hibernate 取出來的時候同樣是取得 UTC 時間做綁定

2023-12-25T11:31:56.682+08:00 DEBUG 29184 --- [nio-8080-exec-2] org.hibernate.SQL : select d1_0.id,d1_0.datetime,d1_0.timestamp from dt d1_0 where d1_0.id=?
2023-12-25T11:31:56.682+08:00 TRACE 29184 --- [nio-8080-exec-2] o.h.r.j.i.ResourceRegistryStandardImpl : Registering statement [HikariProxyPreparedStatement@2074824531 wrapping com.mysql.cj.jdbc.ClientPreparedStatement: select d1_0.id,d1_0.datetime,d1_0.timestamp from dt d1_0 where d1_0.id=** NOT SPECIFIED **]
2023-12-25T11:31:56.684+08:00 TRACE 29184 --- [nio-8080-exec-2] o.h.r.j.i.ResourceRegistryStandardImpl : Registering result set [HikariProxyResultSet@310872211 wrapping com.mysql.cj.jdbc.result.ResultSetImpl@5b842ce6]
2023-12-25T11:31:56.685+08:00 DEBUG 29184 --- [nio-8080-exec-2] o.hibernate.orm.results.loading.entity : (EntityResultInitializer) Hydrated EntityKey (com.example.lab.spring.boot.jpa.persistent.data.DtEntity): 2
2023-12-25T11:31:56.686+08:00 DEBUG 29184 --- [nio-8080-exec-2] o.hibernate.orm.results.loading.entity : (EntityResultInitializer) Created new entity instance [com.example.lab.spring.boot.jpa.persistent.data.DtEntity#2] : 1223328396
2023-12-25T11:31:56.686+08:00 DEBUG 29184 --- [nio-8080-exec-2] org.hibernate.orm.results : Extracted JDBC value [1] - [2023-12-25T03:31:52.399Z]
2023-12-25T11:31:56.686+08:00 DEBUG 29184 --- [nio-8080-exec-2] org.hibernate.orm.results : Extracted JDBC value [2] - [2023-12-25T03:31:52.399Z]

可以參考我寫的 lab-spring-boot-datetime-with-timezon 範例專案

結論

原則上最好的情況就是 server 端不論接收、傳送或是計算時間都採用 UTC 時區為準，才能最大程度保證時間資料的正確性，而不同時區的變換則在 client 端依照需求自行轉換；除非有需要依照不同 client 端時區做相對時間 (例如本週、本月等) 的計算才會需要依照 client 提供的時區做某種程度的轉換，但也應該最終都要轉成 UTC 時區時間做最終計算，因此不論在後端或 DB 保存上，也都最好一致採用 UTC 做交互及保存

而由前面的討論可以得知原則上 Hibernate 預設已經是採取這樣的方案，但如果有需要越過 JPA/Hibernate 去使用到 JDBC API 的話，建議依照 MySQL JDBC Driver 不同的版本，在 JDBC Url 上加上設定 session timezone 的參數，如在 MySQL JDBC Driver 8.0.23 之後的版本可以加上 connectionTimeZone=UTC 及 forceConnectionTimeZoneToSession=TRUE 兩項參數，來確保 JDBC 在保存及取得 TIMESTAMP 或 DATETIME 資料型態時都會維持 UTC 時區時間

而 server 端最好也能設定 JVM 時區為 UTC，而不要依賴 OS 的時區，比較能保證運行的穩定性

另外就是要考量是否會直接使用到 JDBC API 或只會只用 JPA 介面，如果要使用到 JDBC API 則考慮使用 ZonedDateTime 或 OffsetDateTime 來做 MySQL TIMESTAMP 或 DATETIME 的 mapping，如果只使用到 JPA，那可以考慮選用 Instant 會讓時區轉換更單純

但以上設定最好都是在專案或環境剛開始的時候就能設定好，如果是 legacy 專案環境，就只能視狀況做不同的調整，而不能一概而論

Reference

- https://blog.idontwannarock.dev/2023/12/java_time_mapping_mysql_datetime_timezone/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

MySQL 8.0 使用 UTC_TIMESTAMP() 當作 DATETIME 欄位預設值 bug

Tue, 31 Oct 2023 11:59:03 +0800

Howard Tech Note https://blog.idontwannarock.dev/2023/10/mysql_8_utc_timestamp_as_datetime_default_bug/ -

情境描述

最近在處理 MySQL 的時候採到一個坑

我的使用情境是需要一個 create date 紀錄資料產生時的 UTC 時間精準到 millisecond

首先考慮到 MySQL 的 TIMESTAMP 資料型態是採用 epoch second 加上額外的 fractional seconds 精準到 microseconds，也就是最多記錄到 ‘2038-01-19 03:14:07.999999’ 就會 overflow，如果採用 DATETIME(3) 可以記錄到 ‘9999-12-31 23:59:59.999’

接著因為欄位必填，所以考慮設定預設值，此時有幾種選擇，NOW()、CURRENT_TIMESTAMP、UTC_TIMESTAMP，其中 NOW() 與 CURRENT_TIMESTAMP 都會依照 MySQL 系統時區產生時間，但是 DATETIME 並不保存時區資訊，所以為了避免時區問題，所以選擇預設值設定為 (UTC_TIMESTAMP(3))，剛好在 8.0.13 開始可以將 DATETIME 資料型態的欄位預設值設為 function (UTC_TIMESTAMP())

但是設定完後發生了很奇怪的問題，後續進行的 ALTER TABLE DDL 操作都會失敗並拋出 ERROR 1067: Invalid default value for <columnName> 錯誤，例如執行以下 sql

ALTER TABLE tableName ADD COLUMN newColumnName BIGINT NULL;

明明新增的是 BIGINT 而且沒有預設值，卻拋出 ERROR 1067: Invalid default value for createdDateColumn 的錯誤，簡直莫名其妙讓人丈二和尚摸不著頭腦

Bug 狀況

經過確認是 MySQL 在 8.0.23 以前的 bug，在 8.0.24 之後已經修正，可以參考這張 bug report 的描述

簡單來說就是如果在 table 中有欄位的預設值不是 constant，例如我使用的 (UTC_TIMESTAMP(3))，則後續的 ALTER TABLE DDL 操作都會失敗並拋出 1067 錯誤

重現步驟

建議使用 docker 啟動一個 8.0.13-8.0.23 之間版本的 MySQL

docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:8.0.23

然後連上 MySQL

docker exec -it some-mysql bash
mysql -uroot -p

建立 table

use test;
create table test_timestamp (id int not null auto_increment, created datetime not null default (utc_timestamp()), primary key (id));

此時執行 ALTER TABLE DDL

alter table test_timestamp add column test varchar(63) null;

應該就會看到 ERROR 1067: Invalid default value for created 的錯誤訊息

解決方式

以我碰到的情況而言其實有兩種解決方式

第一種就是乖乖升級，bug 自解

第二種就是 bug report 裡面有人提出來的 workaround 方式

流程大致上就是把原本設定為 UTC_TIMESTAMP() function 的欄位預設值改為 CURRENT_TIMESTAMP() function，然後執行原本預定要執行的 ALTER TABLE DDL，最後再把 CURRENT_TIMESTAMP() 的欄位型態改回 UTC_TIMESTAMP() function 即可

這兩個方式我都實測過可行，但各有需要考慮的狀況

第一種方式當然是怕升級過程有 downtime 或甚至其他升級失敗的狀況，這主要就考驗公司 SRE 之類單位的強度

第二種方式則是要自己考量在改成 CURRENT_TIMESTAMP() 期間產生髒資料的處理，例如可能新增的一筆資料時區可能不是 UTC 的問題，如果時區是 UTC+X 的還好處理，如果是 UTC-X 的就會很麻煩，可能要預先做其他處理，例如可能要額外新增時區欄位

Reference

- https://blog.idontwannarock.dev/2023/10/mysql_8_utc_timestamp_as_datetime_default_bug/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Spring JPA Projection with Converter

Wed, 20 Sep 2023 09:37:21 +0800

Howard Tech Note https://blog.idontwannarock.dev/2023/09/spring_jpa_projection_converter/ -

Pre-requisite

JDK 11+
Spring Boot 2+

情境描述

使用 JPA 做單表查詢非常方便，但有時候因為效能考量，會出現 DB data type 與 Java data type 無法直接對應或需要做一些客製化調整

例如在保存狀態時，因為狀態通常有固定且少量的值，所以會考慮採用 int 而非 varchar 來保存，在存儲大小跟查詢效能上都較優

CREATE TABLE CHATROOM
(
 ...
 `STATUS` INT NOT NULL,
 ...
);

但在程式面都採用 Java 的 int 來操作狀態，可讀性相對較低，所以可能會考慮採用 enum 來操作，可讀性較佳且有 type check

public enum ChatroomStatus {
 CLOSED, ACTIVE
}

設定 Converter

但 JPA 預設並不能將 Java enum 與 MySQL int 做 mapping，所以會需要提供 converter 讓 JPA 知道怎麼做轉換

首先需要調整 enum 如下

public enum ChatroomStatus {
 CLOSED(0),
 ACTIVE(1);

 private final int value;

 ChatroomStatus(int value) {
 this.value = value;
 }

 public int value() {
 return this.value;
 }

 public static ChatroomStatus of(int value) {
 for (ChatroomStatus target : ChatroomStatus.values()) {
 if (target.value == value) {
 return target;
 }
 }
 return null;
 }
}

接著要提供 converter

import jakarta.persistence.AttributeConverter;
import jakarta.persistence.Converter;

@Converter(autoApply = true)
public class ChatroomStatusConverter implements AttributeConverter<ChatroomStatus, Integer> {

 @Override
 public Integer convertToDatabaseColumn(ChatroomStatus attribute) {
 if (attribute == null) {
 return null;
 }
 return attribute.value();
 }

 @Override
 public ChatroomStatus convertToEntityAttribute(Integer dbData) {
 if (dbData == null) {
 return null;
 }
 return ChatroomStatus.of(dbData);
 }
}

最後提供 entity

@Entity
@Table(name = "CHATROOM")
public class ChatroomDo {
 ...
 @NotNull
 @Column(name = "STATUS", nullable = false)
 private ChatroomStatus status;
 ...
}

就可以正常使用 repository 做 CRUD 操作，而同時在 DB 當中 STATUS 為 0 代表 chatroom closed、1 代表 chatroom active

第二種情境描述

有時候我們會需要做一些複雜查詢，尤其是使用到其他 table 做 join 查詢，而且 select 的欄位不一定只選擇一個 entity 包含的欄位，此時就會需要利用 JPA 的 projection 功能

有些情況可以用關聯來處理，但以下假設並沒有在 JPA 設定關聯，而是直接用 native SQL join 的方式做查詢

例如以下 table

CREATE TABLE MESSAGE
(
 ...
 TYPE INT NOT NULL,
 REPLIED_MESSAGE_ID BIGINT,
 ...
)

對應的 MessageDo entity 如下

@Entity
@Table(name = "MESSAGE")
public class MessageDo {
 ...
 @Column(name = "TYPE")
 private MessageType type;
 @Column(name = "REPLIED_MESSAGE_ID")
 private Long repliedMessageId;
 ...
}

其中 MessageType 如下

public enum MessageType {
 TEXT(1),
 IMAGE(2),
 ...

 private final int value;

 MessageType(int value) {
 this.value = value;
 }

 public int value() {
 return this.value;
 }

 public static MessageType of(int value) {
 for (MessageType target : MessageType.values()) {
 if (target.value() == value) {
 return target;
 }
 }
 return null;
 }
}

按照慣例，提供 converter 如下

import jakarta.persistence.AttributeConverter;
import jakarta.persistence.Converter;

@Converter(autoApply = true)
public class MessageTypeConverter implements AttributeConverter<MessageType, Integer> {

 @Override
 public Integer convertToDatabaseColumn(MessageType attribute) {
 if (attribute == null) {
 return null;
 }
 return attribute.value();
 }

 @Override
 public MessageType convertToEntityAttribute(Integer dbData) {
 if (dbData == null) {
 return null;
 }
 return MessageType.of(dbData);
 }
}

此時若需要取得一個 message 以及其回覆 message 的內容，則 JPA query method 就無法 return MessageDo，所以此時我們採用 JPA interface-based projection 來達成此操作，首先按照官方 doc 提供 interface 如下

public interface MessageViewDo {
 ...
 MessageType getType();
 Long getRepliedMessageId();
 MessageType getRepliedMessageType();
 ...
}

然後是 query 如下

public interface MessageDao extends JpaRepository<MessageDo, Long> {

 @Query(value = "SELECT " +
 ...
 " m.TYPE, " +
 " rm.ID AS repliedMessageId, "
 " rm.TYPE AS repliedMessageType, "
 ...
 "FROM MESSAGE m " +
 "LEFT JOIN MESSAGE rm ON m.REPLIED_MESSAGE_ID = rm.ID " +
 "WHERE m.ID = :id", nativeQuery = true)
 Optional<MessageViewDo> findMessageViewById(Long id);
}

此時當我們使用的時候，會開心地發現取出來的 MessageType 值有問題，要不是取出來的值不對，就是會報 org.springframework.core.convert.ConversionFailedException 的錯誤，仔細看 cause 還是 Caused by: java.lang.ArrayIndexOutOfBoundsException？

這是因為 JPA 的 interface-based projection 實際上是用 proxy 來包住取得的 result，等到使用者要使用到物件的時候才做轉換，而且因為我們做的是 open projection (projection 的結果並非基於 entity class)，所以 JPA 無法像 closed projection (projection 結果基於 entity) 那樣從原始的 entity 身上取得 metadata 做轉換，所以只能用 Spring 預設的 converter 來做轉換

是的，因為無法取得 entity 的 metadata，所以此時使用的不是 JPA 的 converter 而是 Spring Core 自帶的 converter，而我們並沒有將我們自定義的 Spring converter 註冊給 Spring DI container，所以它只會用預設的方式去做 int -> enum 的轉換

而 Spring 預設對 int -> enum 的轉換是依照 enum 的 ordinal (順序) 做轉換，而且 ordinal 是從 0 開始，所以你可能會很容易看到轉換出來的 MessageType 比 DB 中的剛好大一號，例如 DB 中的 TYPE 是 1 應該代表的是 TEXT，但取出來卻變成 IMAGE 這樣的情況；更甚者，如果 DB 的值剛好大於等於 enum 的 size 就會報 org.springframework.core.convert.ConversionFailedException

因此，很自然的我們就應該要提供 converter 給 Spring

import org.springframework.core.convert.converter.Converter;
import org.springframework.lang.NonNull;

import java.util.Arrays;

public class MessageTypeConverter implements Converter<Integer, MessageType> {

 @Override
 public MessageType convert(@NonNull Integer source) {
 if (Arrays.stream(MessageType.values()).anyMatch(target -> target.value == source)) {
 return MessageType.of(source);
 }
 return null;
 }
}

但這時候問題就來了，要怎麼註冊這個 converter？這個時候就要看 Spring Boot 的版本了

Spring Boot 2.4.0 以前

import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.event.EventListener;
import org.springframework.core.convert.support.DefaultConversionService;

@Configuration
public class ConverterConfig {

 @EventListener(ApplicationReadyEvent.class)
 public void config() {
 DefaultConversionService conversionService = (DefaultConversionService) DefaultConversionService.getSharedInstance();
 conversionService.addConverter(new MessageTypeConverter());
 }
}

Spring Boot 2.4.0 以後

因為 Spring Boot 2.4.0 以後沒辦法用 DefaultConversionService.getSharedInstance() 的方式，所以最後參考了這裡提供的方式，用反射來註冊 converter

import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.event.EventListener;
import org.springframework.core.convert.support.GenericConversionService;

import java.lang.reflect.Field;

@Configuration
public class JpaProjectionConverterConfig {

 @EventListener(ApplicationReadyEvent.class)
 public void offsetDateTimeConversion() throws ClassNotFoundException, NoSuchFieldException, IllegalAccessException {
 Class<?> aClass = Class.forName("org.springframework.data.projection.ProxyProjectionFactory");
 Field field = aClass.getDeclaredField("CONVERSION_SERVICE");
 field.setAccessible(true);
 GenericConversionService service = (GenericConversionService) field.get(null);

 service.addConverter(new MessageTypeConverter());
 }
}

如此就可以利用框架自動 mapping Java enum 與 MySQL int

另外提一下，Java 的 Instant 或 OffsetDateTime 與 MySQL datetime 之間也有類似的問題，所以也需要提供一個 converter 做 Instant 或 OffsetDateTime 與 java.sql.Timestamp 之間做轉換

JPA 會把 MySQL 的 datetime 以 java.sql.Timestamp 取出來

Reference

- https://blog.idontwannarock.dev/2023/09/spring_jpa_projection_converter/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Scoop 介紹及用法

Tue, 20 Jun 2023 10:51:39 +0800

Howard Tech Note https://blog.idontwannarock.dev/2023/06/scoop/ -

Linux 有 apt, yum、MacOS 有 Homebrew、Windows 有 Chocolatey

但今天要介紹 Windows 環境的另外一個 command line 套件管理工具 Scoop

在 Windows 環境，比較有名的 command line 套件管理工具是 Chocolatey，但今天要介紹的 Scoop 有一項 Chocolatey 沒辦法做到的好處，就是可以切換 Path Environment Variable

安裝

Scoop 的安裝非常簡單，打開非 Administrator (系統管理員) 的 Powershell，並輸入以下指令即可安裝

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

使用

Scoop 既然是套件管理工具，那重要的工作就是安裝套件，而 Scoop 有支援什麼套件固然可以直接 Google 的到，但其實也不是沒有方式直接在 command line 搜尋

例如想安裝 7zip 壓縮工具，可以在 powershell 當中這樣搜尋

scoop search 7zip

應該會出現如下的結果

第一行說明代表這次結果是在本地的 bucket 當中搜尋到的，表格當中的 Name 就是套件名稱，之後所有操作都要輸入 Name 當中顯示的完整名稱，Source 就是指套件所在的 bucket

這邊如果你不確定是哪個套件名稱，也可以用以下指令看一下簡介，例如

scoop info 7zip

這時候確定要安裝哪一個套件名稱，這時候就可以輸入以下指令做安裝

scoop install 7zip

這時候 console 會顯示經過一連串的操作，最後看到這一行就代表安裝成功

如果要解除安裝也是簡單輸入以下指令

scoop uninstall 7zip

如果想查詢本地安裝了哪些套件

scoop list

也可以搜尋本地安裝的套件名稱

scoop list maven

最後如果要更新某個套件，可以輸入

scoop update maven

Bucket

接著這邊要了解的是 Scoop 並不像 Chocolatey 的搜尋是在網路上對所有套件做即時搜尋，Scoop 有 bucket 的概念，每個 bucket 都像是一組套件的資料夾

在安裝 Scoop 時就會預設安裝 main bucket，裡面應該預設就有一千多種常用套件，而 Scoop 的搜尋也是優先在本地已安裝的 bucket 裡面做搜尋，如果本地的 bucket 搜尋不到，才會到網路上其他已知 (known) 的 bucket 中做搜尋

所以首先想要確認本地安裝了哪些 bucket 就輸入以下指令

scoop bucket list

如果想查詢有哪些已知的 bucket (本地及遠端)

scoop bucket known

但這個列表也許已過時，這時候可以輸入以下指令更新 Scoop 後，再做查詢

scoop update

如果想安裝指定 bucket 到本地

scoop bucket add games

移除 bucket

scoop bucket rm games

以上差不多就是 Scoop 常見的基本用法

JDK 切換

有一種情境我們會安裝某一種套件，但要同時安裝多種版本，使用的時候需要切換不同的版本，例如安裝 JDK，可能會需要同時安裝 1.8、11 甚至 17，但使用的時候會需要按照需要執行的專案來切換不同版本的環境變數

在 Unix-like 的環境，大多都可以使用 SDKMAN，但偏偏 SDKMAN 原生並不支援在 Powershell 操作，只能透過 Cygwin 等方式 workaround，但同時也限制環境變數只在 Cygwin 當中生效，而無法使用 Powershell 操作

如果要在 Powershell 中操作，以往只能安裝好 JDK 後，再設定環境變數 JAVA_HOME 指定到安裝好的位置，然後每次要使用不同 JDK 版本，就要手動修改 JAVA_HOME 環境變數，或輸入不太好記的指令去操作，如果 JDK 版本更新，又要整個重頭再來，相當的麻煩

但 Scoop 本身提供了相當方便的指令，可以如 SDKMAN 一樣簡單的安裝多種不同版本的 JDK，並且在需要的時候非常簡單的切換不同的版本

首先我們可以先安裝幾種不同版本的 JDK

scoop bucket add java
scoop install zulu-jdk
scoop install zulu11-jdk

此時我們本地已安裝了 11 及 20 兩種版本的 JDK，在安裝的時候就會自動設定好環境變數

接著如果我們要切換使用 JDK 20

scoop reset zulu-jdk

這時我們就可以看到 Java 的版本被改變了

Reference

- https://blog.idontwannarock.dev/2023/06/scoop/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Gradle + Docker Multi-stage build

Thu, 15 Dec 2022 10:18:10 +0800

Howard Tech Note https://blog.idontwannarock.dev/2022/12/gradle_docker_multi_stage_build/ -

Java 專案整合 Docker multi-stage build 系列：

Maven + Docker Multi-stage build
Gradle + Docker Multi-stage build

前一篇講過 Maven 配合 Docker multi-stage build 的優化概念跟實作，這篇順便來講一下 Gradle 的部分

Docker Multi-stage Build

前一篇已經介紹過建置 Java 專案配合 Docker multi-stage build 的優化概念，這邊就不再贅述，直接上 Dockerfile：

FROM gradle:7.6-alpine AS Cache
WORKDIR /opt/app
ENV GRADLE_USER_HOME /cache
COPY build.gradle ./
RUN gradle --no-daemon dependencies --stacktrace

FROM gradle:7.6-jdk11-alpine AS Builder
WORKDIR /opt/app
COPY --from=Cache /cache /home/gradle/.gradle
COPY build.gradle settings.gradle ./
COPY src /opt/app/src
RUN gradle --no-daemon build --stacktrace --offline

FROM azul/zulu-openjdk-alpine:11-jre-headless
WORKDIR /opt/app
COPY --from=Builder /opt/app/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

步驟同樣大致如下：

依照 build.gradle 下載所有 dependencies
利用前一階段下載好的 dependencies 離線建置專案
利用前一階段建置好的 jar 檔運行應用程式

Gradle 單就配合 Docker multi-stage build 的實作方面比 Maven 方便得多，最起碼就沒有 default lifecycle plugin 的 dependencies 不會自動下載的 bug，所以直接使用 gradle dependencies 的指令就可以直接下載到所有建置時需要用到的 dependencies，完全不需要像 Maven 那樣為了要下載 plugin 抓不到的 dependencies 而去做 workaround

另外同樣要注意盡量選用較精簡的 base image，在 Gradle 這邊就盡量都選用 alpine 結尾的 image

參考

- https://blog.idontwannarock.dev/2022/12/gradle_docker_multi_stage_build/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Maven + Docker Multi-stage Build

Wed, 14 Dec 2022 14:14:44 +0800

Howard Tech Note https://blog.idontwannarock.dev/2022/12/maven_docker_multi_stage_build/ -

Java 專案整合 Docker multi-stage build 系列：

Maven + Docker Multi-stage build
Gradle + Docker Multi-stage build

現代常見的 CI/CD 流程經常會使用容器化 (containerized) 的方式來幫助建置環境及部署

以 Java + Maven 專案舉例，一個比較通用的 Dockerfile 可能長這樣：

FROM maven:3.8-openjdk-11

WORKDIR /opt/app

COPY src/main/resources /opt/app/src/main/resources
COPY src/main/java /opt/app/src/main/java
COPY pom.xml .
RUN mvn -B -e clean package

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "demo.jar"]

這個 Dockerfile 其實沒有問題，完全可以正常運行，但它使用上有一個地方不太方便，就是每次運行到 RUN mvn -B -e clean package 這行的時候，除非程式碼跟 pom.xml 都沒有變動，否則所有 dependencies 都會重新下載一遍，如果專案比較大型，那光下載 dependencies 可能就會要花很久的時間

Docker Multi-stage Build

於是就有人使出了 Docker multi-stage build 這招

FROM maven:3.8-openjdk-11 as DEPENDENCIES
WORKDIR /opt/app
COPY pom.xml .
RUN mvn -B -e -C org.apache.maven.plugins:maven-dependency-plugin:3.3.0:go-offline

FROM maven:3.8-openjdk-11 as BUILDER
WORKDIR /opt/app
COPY --from=DEPENDENCIES /root/.m2 /root/.m2
COPY src/main/resources /opt/app/src/main/resources
COPY src/main/java /opt/app/src/main/java
COPY pom.xml .
RUN mvn -B -e clean package

FROM openjdk:11-jre
WORKDIR /opt/app
COPY --from=BUILDER /opt/app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

簡單來說，在過程中會分成三段建置，第一段會依照 pom.xml 將所有 dependencies 下載下來；第二段會利用第一段下載的 dependencies 來建置專案；第三段則是運行第二段建置好的專案 jar 檔。

這樣做有什麼好處呢？主要差別在於「建置時間」跟「最終 image 的大小」

建置時間

Docker 的 image 是由一層一層的 layer 疊加而成，每一層其實都是一個 image，只是中間層的 image 是 read only 而且一般指令是找不到的，只有最上層的 image 是 read/write 都可以的 layer，也才能被操作

source: MetricFire How to Build Optimal Docker Images

在 Dockerfile 當中的每一行都是一層 layer，每層 layer 都是一個 image，而 Docker 在 build 的過程是會針對 image 做 cache，也就是 Dockerfile 當中每一行運行的指令相關的資源沒有變動，Docker 就會直接使用已有的 image

以前面的 Dockerfile 來說，如果第三行 COPY pom.xml . 複製進來的 pom.xml 沒有變動，則第四行 RUN mvn -B -e -C org.apache.maven.plugins:maven-dependency-plugin:3.3.0:go-offline 也不會實際運行，而是直接使用前一次建置出來對應 layer 的 image

利用 Docker 這樣的特性，加上一般開發的時候 pom.xml 不太會變動的前提下，在大部分使用這份 Dockerfile 做建置的時候，第一階段的步驟都會使用 cache，從而節省每次建置都要重新下載 dependencies 的時間

Image 大小

不知道有多少人留意過你 build 出來的 image 大小？

前面第一種作法 build 出來的 image 本身會包含了 base image (本身就包含 maven 及 jdk)、程式碼、下載下來的所有 dependencies，以及建置出來的 jar 檔

其中運行 jar 檔時並不需要 maven，也不需要 JDK 而只需要 JRE，以 Spring Boot 來說，所有運行需要的 dependencies 都已經包在 jar 檔裡面 (fat jar)，所以 image 裡面的 .m2 資料夾也是重複的

這樣 build 出來的 image 動輒幾百 mb，雖然現在硬碟便宜，但有串 CI/CD 的開發流程經常 dev 分支每 push 一次就建置一個 image，那占用的空間就大了，如果是用雲端服務，那燒的就是老闆的錢

所以 image 大小 matters！

先重新順一下前面這份 multi-stage build 的 Dockerfile 流程：

依照 pom.xml 下載所有 dependencies
直接使用前一階段下載好的 dependencies 來建置專案 jar 檔
直接使用前一階段建置好的 jar 檔來運行

從流程中我們可以看到最終產出的 image 本身只帶有 base image 以及建置好的 jar 檔、base image 只包含 headless JRE、layer 只有五層、也不帶有前面階段使用到的 dependencies，甚至也不包含建置需要的 maven，因此最終的 image 的大小就會明顯的下降

優化

Base Image

但其實前面這份 Dockerfile 還有優化空間，比較簡單的就是使用更精簡的 base image，也就是盡量選擇只包含運行該 stage 需要的最少功能的 image

FROM maven:3.8-openjdk-11-slim as DEPENDENCIES
WORKDIR /opt/app
COPY pom.xml .
RUN mvn -B -e -C org.apache.maven.plugins:maven-dependency-plugin:3.3.0:go-offline

FROM maven:3.8-openjdk-11-slim as BUILDER
WORKDIR /opt/app
COPY --from=DEPENDENCIES /root/.m2 /root/.m2
COPY src/main/resources /opt/app/src/main/resources
COPY src/main/java /opt/app/src/main/java
COPY pom.xml .
RUN mvn -B -e clean package

FROM azul/zulu-openjdk-alpine:11-jre-headless
WORKDIR /opt/app
COPY --from=BUILDER /opt/app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

一般來說帶有 alpine 或 slim 結尾的 image 都會是相對比較好的選擇；如果只是要用來運行無 GUI 的 Java 應用程式的話，盡量選擇 headless

Maven

如果你有仔細觀察建置過程的 log 的話，應該會發現在運行第 12 行 RUN mvn -B -e clean package 的時候，maven 還是會下載一些 dependencies

這就很奇怪啊，照理來說前一階段應該就把全部的 dependencies 都下載下來啦，畢竟這就是 dependency:go-offline 這個 goal 的目的不是嗎？

但很抱歉，你要說這是 plugin 的 bug 或是原本的功能都好，總之，它只會下載 pom.xml 上面有明示列出的 artifact，而且甚至連 <plugin> 標籤內部的 <dependencies> 標籤當中的 artifact 都不會下載

這個 issue 從 2007 年開到現在都還沒解決，可以參考 MDEP-82

再加上有些 maven 預設 lifecycle 或 goal 需要動態載入的 dependencies 也並不在下載的目標當中，就會造成在第二階段真正開始建置專案的時候會需要下載缺少的 dependencies

某些 plugin 的 dependencies 甚至不是列在 pom.xml 當中，而是利用 class loader 的方式超級動態載入，這也是 maven-dependency-plugin 無能為力的部分

如果建置過程都有連網還好，有些 CI/CD 的流程在建置這個階段是會跟網路隔離的，或是會利用建置這個步驟順便做測試，但為了測試環境的「乾淨」而限制連網功能，這個情況就很尷尬了，各種建置失敗

在 plugin 修正之前，只能採取各種 workaround，以下介紹一種比較麻煩，但相對不會變更太多建置步驟或在建置出來的 jar 檔或甚至 git repo 中增加不必要 dependencies 的方式

Workaround

首先將 Dockerfile 調整如下：

FROM maven:3.8-openjdk-11-slim as DEPENDENCIES
WORKDIR /opt/app
COPY pom.xml .
RUN mvn -B -e -C clean org.apache.maven.plugins:maven-dependency-plugin:3.3.0:go-offline

FROM maven:3.8-openjdk-11-slim as BUILDER
WORKDIR /opt/app
COPY --from=DEPENDENCIES /root/.m2 /root/.m2
COPY src/main/resources /opt/app/src/main/resources
COPY src/main/java /opt/app/src/main/java
COPY pom.xml .
RUN mvn -B -e -o clean package

FROM azul/zulu-openjdk-alpine:11-jre-headless
WORKDIR /opt/app
COPY --from=BUILDER /opt/app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

主要改動有兩個部分，一是在第一階段也運行 clean lifecycle 以下載相關的 dependencies；二是在第二階段建置加上 -o 參數，這是為了讓 maven 在 offline 的狀況下進行建置，也就是強制 maven 不連網

第一次 build 的時候應該會發現在 mvn clean package 階段報錯，這時候往前找一下，應該會找到類似以下這段 log：

#16 1.770 [INFO] --------------------------------[ jar ]---------------------------------
#16 2.025 [WARNING] The POM for org.apache.tomcat:tomcat-annotations-api:jar:9.0.65 is missing, no dependency information available
#16 2.083 [WARNING] The POM for net.minidev:json-smart:jar:2.4.8 is missing, no dependency information available
#16 2.131 [WARNING] The POM for net.bytebuddy:byte-buddy:jar:1.12.13 is missing, no dependency information available
#16 2.131 [WARNING] The POM for net.bytebuddy:byte-buddy-agent:jar:1.12.13 is missing, no dependency information available
#16 2.528 [WARNING] The POM for com.rabbitmq:amqp-client:jar:5.14.2 is missing, no dependency information available
#16 2.589 [WARNING] The POM for org.glassfish.jaxb:jaxb-runtime:jar:2.3.6 is missing, no dependency information available
#16 2.823 [WARNING] The POM for com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:jar:2.13.3 is missing, no dependency information available
#16 2.830 [WARNING] The POM for org.webjars:webjars-locator-core:jar:0.50 is missing, no dependency information available
#16 2.840 [WARNING] The POM for org.apache.httpcomponents:httpcore:jar:4.4.15 is missing, no dependency information available

以上這段就是在說明 maven 在執行到 jar 這個 goal 的時候缺少哪些 dependencies

這時候我們就會需要回到 pom.xml，依照上面那段 log 缺少的 artifact，在 <build> 標籤裡面加入以下這段：

<pluginManagement>
 <plugins>
 <plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-clean-plugin</artifactId>
 <dependencies>
 <dependency>
 <groupId>org.apache.tomcat</groupId>
 <artifactId>tomcat-annotations-api</artifactId>
 <version>9.0.65</version>
 </dependency>
 <dependency>
 <groupId>net.minidev</groupId>
 <artifactId>json-smart</artifactId>
 <version>2.4.8</version>
 </dependency>
 <dependency>
 <groupId>net.bytebuddy</groupId>
 <artifactId>byte-buddy</artifactId>
 <version>1.12.13</version>
 </dependency>
 <dependency>
 <groupId>net.bytebuddy</groupId>
 <artifactId>byte-buddy-agent</artifactId>
 <version>1.12.13</version>
 </dependency>
 <dependency>
 <groupId>com.rabbitmq</groupId>
 <artifactId>amqp-client</artifactId>
 <version>5.14.2</version>
 </dependency>
 <dependency>
 <groupId>org.glassfish.jaxb</groupId>
 <artifactId>jaxb-runtime</artifactId>
 <version>2.3.6</version>
 </dependency>
 <dependency>
 <groupId>com.fasterxml.jackson.dataformat</groupId>
 <artifactId>jackson-dataformat-yaml</artifactId>
 <version>2.13.3</version>
 </dependency>
 <dependency>
 <groupId>org.webjars</groupId>
 <artifactId>webjars-locator-core</artifactId>
 <version>0.50</version>
 </dependency>
 <dependency>
 <groupId>org.apache.httpcomponents</groupId>
 <artifactId>httpcore</artifactId>
 <version>4.4.15</version>
 </dependency>
 </dependencies>
 </plugin>
 </plugins>
</pluginManagement>

這段是為了告訴 maven maven-clean-plugin 需要指定的這些 dependencies

請注意一定要掛在 maven-clean-plugin 底下，因為這就是 clean lifecycle 對應的 plugin，這樣我們在第一階段執行 clean 的時候才會下載這些缺少的 artifact

參考

- https://blog.idontwannarock.dev/2022/12/maven_docker_multi_stage_build/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

SpringFox to SpringDoc

Mon, 12 Dec 2022 09:24:17 +0800

Howard Tech Note https://blog.idontwannarock.dev/2022/12/springfox_to_springdoc/ -

以 Spring Boot 生態來說，比較主流的 documentation 方式應該就是 Swagger，以往應該多數人都是使用 SpringFox library，但近幾年也漸漸興起使用 SpringDoc，所以就做了一點筆記，紀錄要怎麼從 SpringFox 轉移到 SpringDoc

比較

這兩者同樣都有實作 OpenAPI 3.0，為什麼我們需要從 SpringFox 轉移使用 SpringDoc？

springfox-boot-starter 包含許多 Spring 的 transitive dependencies；springdoc-openapi-ui 則是 standalone 的 library，並沒有跟 Spring 的依賴
springfox-boot-starter 需要額外 dependency 才有 Swagger UI 的呈現；springdoc-openapi-ui 則已經內含 Swagger UI
SpringDoc 在一些細節功能上更強大，例如提供陣列參數更好的 UI 做輸入
最重要的一點，SpringFox 幾乎已經不再更新；而 SpringDoc 還有在常態維護，因此也能跟較新版本的 Spring 有更好的整合，也能更即時的修正 bug

升級步驟

相當簡單，參考官方文件即可

因為都是實作 OpenAPI，就算 SpringFox 有實作 2.0 版，但跟 3.0 其實差異也不大

主要就是改一下 dependency，然後 annotation 調整一下，其他幾乎沒有不同

注意事項

Spring Security

若有整合 Spring Security，則可以在 controller 透過加註 @AuthenticationPrincipal 註解注入驗證過的 principal 物件，但這個物件不需要呈現在 Swagger 上

以往 SpringFox 的作法是用 @ApiIgnore 註解來隱藏；SpringDoc 也可以透過 @Parameter(hidden = true) 來隱藏

不過 SpringDoc 還有提供另外一種做法，就是加上以下 dependency，Swagger 上就會自動忽略 @AuthenticationPrincipal

<dependency>
 <groupId>org.springdoc</groupId>
 <artifactId>springdoc-openapi-security</artifactId>
 <version>1.6.13</version>
</dependency>

反向代理

如果有使用反向代理，官方文件中有建議可以設定 server.forward-headers-strategy 為 framework 或 native 的方式；但要注意的是，SpringDoc 是從以下 headers 當中取得 url，並只在第一次產生 ui 的時候取得該值：

RFC7239 規範的 Forwarded Headers
X-Forwarded-Host
X-Forwarded-Port
X-Forwarded-Proto
X-Forwarded-Ssl
X-Forwarded-Prefix

但萬一反向代理做 upstream 的時候沒有帶上這些 headers，或我們可能需要從 Referer header 取得真實來源的 domain，好讓 Swagger UI 做 HTTP 呼叫的時候可以使用

以往在 SpringFox 我們需要從 request 當中取得 Referer header 並解析；但 SpringDoc 可以有更簡單的作法，也就是直接設定 OpenAPI 的 servers 為 / 或是 Spring Boot 的 server.servlet.context-path

以下為 annotation 方式設定範例

@Configuration
@OpenAPIDefinition(info = @Info(
 title = "Product API",
 version = "1.0.0"),
 servers = @Server(url = "${server.servlet.context-path}/")
)
public class SwaggerConfig {
}

或以 programmatic 方式設定：

@Configuration
public class SwaggerConfig {

 @Value("${server.servlet.context-path}")
 private String serversUrl;

 @Bean
 OpenAPI openAPI() {
 return new OpenAPI()
 .info(new Info()
 .title("Product API")
 .version("1.0.0"))
 .servers(List.of(new Server()
 .url(serversUrl + "/")));
 }
}

參考

- https://blog.idontwannarock.dev/2022/12/springfox_to_springdoc/ - This website by Howard Wang is licensed under a Creative Common Attribution-ShareAlike 4.0 International License.

Howard Tech Note

如何在 MySQL 中進行 insert if not exists

準備

insert

insert ignore

replace

insert … on duplicate key update

insert … on duplicate key update id = id

insert … select … not exists

insert … select … not exists … on duplicate key

insert ignore … select … not exists

Conclusion

Reference

Percona XtraDB Cluster MySQL with Docker Compose

環境

作法

compose.yml

conf/custom.cnf

init.sql

init.sh

使用

Reference

.gitattributes 引發的慘案

情況描述

問題原因

權限問題？

Jar 檔毀損？

.gitattributes 4 ni？！

解決辦法

後記

Reference

Java Time 保存到 MySQL DATETIME 時區問題

Pre-requisite

資料類型選擇的考量

時區轉換機制

MySQL JDBC Driver 的時區轉換

Hibernate 的時區轉換

JDBC 4.2 時間格式規範

MySQL JDBC Driver 時間格式支援

Hibernate 5 的 normalization

Hibernate 6 的 TimeZoneStorageType 設定

測試

結論

Reference

MySQL 8.0 使用 UTC_TIMESTAMP() 當作 DATETIME 欄位預設值 bug

情境描述

Bug 狀況

重現步驟

解決方式

Reference

Spring JPA Projection with Converter

Pre-requisite

情境描述

設定 Converter

第二種情境描述

Spring Boot 2.4.0 以前

Spring Boot 2.4.0 以後

Reference

Scoop 介紹及用法

安裝

使用

Bucket

JDK 切換

Reference

Gradle + Docker Multi-stage build

Docker Multi-stage Build

參考

Maven + Docker Multi-stage Build

Docker Multi-stage Build

建置時間

Image 大小

優化

Base Image

Maven

Workaround

參考

SpringFox to SpringDoc

比較

升級步驟

注意事項

`insert`

`insert ignore`

`replace`

`insert … on duplicate key update`

`insert … on duplicate key update id = id`

`insert … select … not exists`

`insert … select … not exists … on duplicate key`

`insert ignore … select … not exists`

`.gitattributes` 4 ni？！

Hibernate 6 的 `TimeZoneStorageType` 設定