Use Flyway or Liquibase

Both ship migration ordering + tracking out of the box. Pick one, put migrations in src/main/resources/db/migration/.

-- V001__initial.sql
CREATE TABLE adk_sessions (...);

-- V002__add_agent_name.sql
ALTER TABLE adk_sessions ADD COLUMN agent_name text;
UPDATE adk_sessions SET agent_name = 'unknown' WHERE agent_name IS NULL;
ALTER TABLE adk_sessions ALTER COLUMN agent_name SET NOT NULL;
Advertisement

Expand-then-contract

Add nullable column, backfill, then set NOT NULL. Never drop a column in the same release the code stops using it.

Advertisement

JSONB avoids most migrations

New metadata fields go in the metadata JSONB. No migration needed. Downside: no strong typing.