Skip to content

Add print only flags to dbos migrate#459

Merged
maxdml merged 4 commits into
mainfrom
migrate-print-only
Jul 24, 2026
Merged

Add print only flags to dbos migrate#459
maxdml merged 4 commits into
mainfrom
migrate-print-only

Conversation

@maxdml

@maxdml maxdml commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Java port of dbos-inc/dbos-transact-py#780: dbos migrate gets two mutually exclusive flags that print SQL to stdout instead of executing it. Stdout stays pure SQL and -- comments (pipeable to a .sql file); neither flag ever connects to a database.

--print-migrations [all|N]

Prints the SQL of all DBOS system database migrations, or of migrations N (1-based) through latest, with per-migration dbos_migrations version bookkeeping mirroring the runner (so an interrupted apply can be resumed from the next migration number):

dbos migrate --print-migrations all > dbos.sql
dbos migrate --print-migrations 10          # migrations 10..latest, no fresh-database prelude
  • all (or 1) emits the fresh-database prelude (CREATE SCHEMA / CREATE TABLE ... dbos_migrations) and is for fresh databases only.
  • Migration 10 (the notifications primary-key backfill, which migration 1 already creates) is always skipped with a comment; no DO $$ guard blocks appear anywhere in the output.
  • The script contains CREATE/DROP INDEX CONCURRENTLY, so it must run outside a transaction block (plain psql, not psql --single-transaction).
  • Invalid values (--print-migrations nope, out-of-range numbers) print an error to stderr and exit 1.

--print-user-role

Prints the SQL granting the application role access to the DBOS system tables. Requires --app-role:

dbos migrate --print-user-role --app-role my_app_role

The two flags cannot be combined. Schema or role names containing quotes are rejected.

Deviations from the Python PR

  • The grant statements now double-quote both the schema and role identifiers (matching Python), and the same shared GRANT_QUERIES templates are used by the execute path — so dbos migrate -r role with unusual schema/role names is also fixed.
  • MigrationManager.generateMigrationScript(schema, useListenNotify, startMigration) validates startMigration (1..latest) with IllegalArgumentException; the CLI maps invalid --print-migrations values to the Python stderr messages.
  • The -- DBOS system database migrations for {url} header masks any password= query parameter in the JDBC URL; when no URL is configured (Java's -D/DBOS_SYSTEM_JDBC_URL is optional, unlike Python's required URL), the header reads ... for the system database.

maxdml added 4 commits July 16, 2026 15:49
Prints the full system database migration SQL (schema creation,
all migrations, version bookkeeping, and optional role grants) to
stdout without connecting to the database, so users can run
'dbos migrate --print-only > migration.sql' and apply it with psql.
Match the final design of dbos-transact-py#780:
- dbos migrate --print-migrations [all|N] prints migrations N..latest to
  stdout without ever connecting to a database; no DO $$ guard blocks,
  migration 10 always skipped with a comment, per-migration version
  bookkeeping mirroring the runner.
- dbos migrate --print-user-role --app-role R prints the GRANT statements;
  mutually exclusive with --print-migrations.
- GRANT_QUERIES now double-quote schema and role identifiers on both the
  print and execute paths.
@maxdml maxdml changed the title Add --print-only flag to dbos migrate Add print only flags to dbos migrate Jul 22, 2026
@maxdml
maxdml merged commit f43f4eb into main Jul 24, 2026
12 checks passed
@maxdml
maxdml deleted the migrate-print-only branch July 24, 2026 22:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants