[rawo]

Closes #138. Part of the 2.0.0 breaking-change set.

Problem

The MySQL schema uses TIMESTAMP(6) for created_at, updated_at and last_attempt. TIMESTAMP ends at 2038-01-19 03:14:07 UTC. After that, every publish() fails under strict mode, and with it every business transaction that publishes.

Fix

• Migration 003__datetime_columns converts the three columns to DATETIME(6), which holds UTC.
  • ALTER … MODIFY converts existing TIMESTAMP values through the session time zone. So the changeset pins time_zone = '+00:00' for the conversion and then restores the previous value: Liquibase may run on a pooled connection that the app reuses.
  • The CURRENT_TIMESTAMP column defaults are dropped. okapi always writes these columns, and a DATETIME default would be in session-local time.
• MysqlOutboxStore binds and reads these columns as UTC LocalDateTime instead of java.sql.Timestamp. Connector/J passes LocalDateTime through unconverted, while a Timestamp is shifted by the JVM zone or connectionTimeZone. Stored values are therefore UTC regardless of JVM, session or driver settings, so no connectionTimeZone/preserveInstants configuration is needed (the issue suggested requiring that).
• Docs: the README migration list, a CHANGELOG entry under Changed (BREAKING), and a new "From 1.x to 2.0.0" section in UPGRADING.md.

Breaking

• On upgrade the migration rebuilds okapi_outbox, and writes to it, including publish(), wait for it. It must be applied before starting 2.0.0 workers.
• Anything that reads these columns directly now gets UTC wall-clock DATETIME values.

Tests

• TimestampColumnTests: a shared suite, which Postgres (Postgres: TIMESTAMP WITHOUT TIME ZONE + java.sql.Timestamp stores JVM-local time; mixed-TZ fleets/DST corrupt ordering, lag, purge #135) will reuse. It runs here through MysqlTimestampColumnsTest:
  • instants in 2040 and 2100 round-trip, and the stored value is checked as UTC text;
  • the purger cutoff works past 2038;
  • a value written with JVM zone Europe/Warsaw and session zone +05:00 (at a DST fall-back instant) is stored as UTC, and reads back correctly under America/Los_Angeles.
• MysqlDatetimeMigrationTest, the upgrade path:
  • applies 001+002 on a session at +05:00 and inserts a row through the old TIMESTAMP columns;
  • applies 003 on the same session;
  • checks that the instants are unchanged, the type is datetime, and the session zone is restored to +05:00.
• ./gradlew ktlintCheck test passes locally.

🤖 Generated with Claude Code

[rawo]

The core of the fix looks right to me. Pinning time_zone = '+00:00' around MODIFY is the correct way to turn the TIMESTAMP instants into UTC wall-clock DATETIME values, and the migration test would fail without the pin. Binding and reading LocalDateTime makes stored values independent of the JVM, session and connectionTimeZone settings. All my comments are about the upgrade path and the docs. I didn't find a code bug.

Cross-cutting (should-fix, docs): existing rows may already be shifted before the migration runs. The migration keeps the stored TIMESTAMP instants. But 1.x could store wrong instants and still read them back correctly. With Connector/J defaults (connectionTimeZone=LOCAL, preserveInstants=true, no forceConnectionTimeZoneToSession), setTimestamp renders the instant in the JVM zone, and the server parses that literal in the session zone. Example: JVM Europe/Warsaw (+02:00), server/session UTC. 1.x writes 12:00Z as '14:00' and stores 14:00Z. 1.x reads it back through the reverse shift and sees 12:00Z. After 003 plus 2.0, the row reads as 14:00Z, two hours in the future. Effects on such a setup:

• old pending rows are claimed after newer ones until the offset passes (FIFO inversion);
• lag metrics are off, possibly negative;
• purging delivered rows is delayed by the offset.

This is the misconfiguration #138 describes, so it isn't rare. A sentence in UPGRADING would cover it: if the JVM zone differed from the MySQL session zone and connectionTimeZone wasn't set, drain the outbox before upgrading or accept the transient shift. A small UPDATE recipe is another option. I'm confident about the driver behaviour, but I haven't run this exact scenario.

Checked and fine:

• The changeset is safe to re-run after a crash between the ALTER and the DATABASECHANGELOG insert: DATETIME → DATETIME doesn't shift values.
• MODIFY keeps the indexes, so the FORCE INDEX claims still find theirs. Comparing DATETIME with a bound LocalDateTime keeps index use for removeDeliveredBefore on (status, last_attempt).
• TimeZone.setDefault in TimestampColumnTests is OK for now. No kotest/JUnit parallelism is configured. MysqlDataSource opens a fresh connection per withTransaction, so the driver really sees the changed default zone, and with the old Timestamp binding the test would fail. If spec concurrency is ever enabled, this test needs isolation.
• The CHANGELOG entry is under Unreleased → Changed (BREAKING), which is the right place.

Question: CI only covers mysql:8.0. The README says "MySQL 8+", and the Exposed runner mentions MariaDB. Has 003 been run on MySQL 8.4/9.x or MariaDB? The session-zone semantics of MODIFY should be the same there, but MariaDB's explicit_defaults_for_timestamp/ON UPDATE handling differs. A quick run would confirm that the defaults and the ON UPDATE behaviour end up dropped as intended.

[rawo]

should-fix (docs): say that 1.x instances must be stopped once 003 runs, not only that 2.0 must not start before it.

The Spring Boot autoconfig runs 003 when the first 2.0 instance starts. In a rolling deploy, 1.x instances are still publishing and claiming at that point. After the migration, 1.x still binds java.sql.Timestamp. Connector/J renders a Timestamp in connectionTimeZone (by default the JVM zone) and the DATETIME column stores that text unconverted. So with a non-UTC JVM, every row 1.x writes or updates in that window gets a local wall-clock value that 2.0 then reads as UTC. 1.x also misreads the rows 2.0 wrote. The wrong values stay in the table for good.

Suggest stating it here, in the README and in the CHANGELOG: either stop every 1.x instance before 003 runs (no rolling deploy across this version), or note that mixed operation is only safe when the 1.x JVMs run in UTC.

[rawo]

should-fix (docs): "blocks writes until it finishes" understates it.

Changing a column's type is ALGORITHM=COPY, so the copy phase permits reads and blocks DML. Two more things matter more in practice:

1. Before it can start, the ALTER must take a metadata lock, so it waits for every open transaction that has touched okapi_outbox. That includes a 1.x worker that is holding its claim transaction open across an HTTP/Kafka delivery, and any business transaction that called publish() and hasn't committed yet.
2. While it waits in the MDL queue, every new statement on the table queues behind it, plain reads included: lag metrics, publish(), everything. MySQL's default lock_wait_timeout is one year, so with Liquibase at startup this can hang the deploy and the app's write path, not just slow it down.

FOR UPDATE SKIP LOCKED claims are blocked during the copy too, not just plain writes.

This is the MySQL counterpart of the CREATE INDEX CONCURRENTLY caveat the README already documents for Postgres 002. Suggest documenting it the same way: stop workers and let in-flight transactions finish. You could also put a bounded SET SESSION lock_wait_timeout = ... in the changeset (and restore it like time_zone) so a blocked migration fails fast instead of stalling the table. README L223 needs the same wording.

[rawo]

should-fix (docs), related to the review body: besides direct readers, existing rows may themselves read back shifted after the upgrade. That happens when 1.x ran with JVM zone ≠ MySQL session zone and connectionTimeZone unset: 1.x stored shifted instants and hid the shift on read. Worth a bullet here, e.g. "drain the outbox first if your JVM and MySQL time zones differed".

[rawo]

nit: 002 states its algorithm explicitly (ALGORITHM=INPLACE, LOCK=NONE). Adding ALGORITHM=COPY, LOCK=SHARED here would make the locking behaviour that the docs describe visible in the SQL. MySQL would also reject the statement instead of picking something else if that combination isn't possible. It doesn't change behaviour on 8.0.

[rawo]

nit: the restore only runs if the ALTER succeeds. If the ALTER fails (lock wait timeout, disk full during the copy), Liquibase stops at that statement, and the connection goes back to the pool still at +00:00. Low impact, because a failed changelog normally aborts startup and the pool goes with it. But the header comment reads as if the pooled connection is always restored. Maybe soften it to "restore it afterwards on success", or note that a failed run should be retried on a fresh connection.

[rawo]

nit: this only checks DATA_TYPE of created_at. Since the changeset also changes the defaults and nullability of all three columns, please assert for created_at, updated_at and last_attempt:

• DATA_TYPE = 'datetime' and DATETIME_PRECISION = 6;
• IS_NULLABLE (only last_attempt is nullable);
• COLUMN_DEFAULT IS NULL and an EXTRA with no on update (the CHANGELOG promises the defaults are dropped).

Also add TABLE_SCHEMA = DATABASE() to the filter. A wrong precision (e.g. DATETIME without (6)) would currently only show up indirectly, through the .25 assertion on created_at.

[rawo]

Addressed the review in 65decfd:

1. Rows 1.x wrote with JVM zone ≠ MySQL session zone read back shifted. This is confirmed driver behaviour and can't be fixed by a conversion, because only the deployment knows the original offset. It's now documented in UPGRADING (new bullet: drain the outbox first in that setup), the README and the CHANGELOG.
2. Rolling deploy. UPGRADING, the README and the CHANGELOG now say to stop every 1.x instance, publishers included, before 003 runs. Mixing versions is only safe if every 1.x JVM runs in UTC.
3. Metadata-lock wait. The changeset now sets lock_wait_timeout = 30 and restores it afterwards, so the MDL queue stall is bounded and a timeout fails the migration, which retries on the next start. The docs describe the real locking: the MDL wait queues reads too, and the copy then blocks writes.
4. Same as 1.
5. ALGORITHM=COPY, LOCK=SHARED is now explicit.
6. The header comment now says session settings are restored on success only.
7. The migration test now checks type, precision, nullability, default and EXTRA of all three columns, filtered by TABLE_SCHEMA, and that lock_wait_timeout is restored.
8. Versions. I did a one-off local run of MysqlDatetimeMigrationTest, MysqlTimestampColumnsTest and MysqlOutboxStoreTest against mysql:8.4, and all pass. MariaDB isn't covered by CI today (that predates this PR) and wasn't run.

./gradlew ktlintCheck test passes.