jadpo migrate

Write and apply migrations.

Keep the database in step with the entities (area 5). new compares the entities with the latest migration's snapshot and writes the next folder in database/migrations/: the whole schema as snapshot.json, the SQL that gets there as postgres.sql, and changes.jadpo when a change needs a decision, such as a value for existing rows; once the decisions are written, new again finishes it. With --drop it removes a retired field or entity for good, once a person accepts it. apply runs a database's pending migrations, each in a transaction, and a computed backfill in batches, each in its own, carrying on where a stopped run left off; status lists the migrations and, with --url, which a database has applied. Until configuration gives each connection its URL, --url names the database.

jadpo migrate <action> [purpose]

Arguments

• action: What to do
• purpose (optional): What a new migration does, in lower_snake_case

Flags

• --url <url>: The PostgreSQL database to apply to or read
• --store <name>: Which store that database is
• --drop <name>: A retired field or entity to remove

On every command

• --json: Print data for tools instead of text
• --full: Show everything a report shortens
• --help: Show every flag, with examples
• --color <when>: Choose when to use colour

jadpo migrate --json writes one JSON document to standard output instead of text, with the same exit code. The document has schemaVersion, command ("migrate"), ok, data (what the command produced, null when it failed) and diagnostics (each error with its rule, reason, next and help). A command that needs a terminal refuses --json and names the flags that do the same job.

Examples

# Write the migration for a new fieldjadpo migrate new add_rating# Finish the latest migration once its decisions are writtenjadpo migrate new# Remove a retired field and its data for goodjadpo migrate new drop_rating --drop Review.rating# Apply the pending migrations to a databasejadpo migrate apply --url postgresql://localhost/shop# List the migrations and which a database has appliedjadpo migrate status --url postgresql://localhost/shop

Errors

• cli.migrate_arguments: A jadpo migrate command names no action, one it doesn't have, a purpose for an action that takes none, or a --drop of what isn't retired
• migration.apply_failed: Applying the project's migrations to a database stopped at a step that failed
• migration.drop_not_accepted: A migration removes data, and no acceptance in the project says a person agreed to it
• migration.store_diverged: The migrations a database has applied don't match the project's: one has changed since it ran, the project doesn't have one, or one comes out of order
• migration.extension_missing: The project's migrations need a PostgreSQL extension, such as pgvector, that the database server doesn't offer or that the role applying them can't create
• migration.extension_outdated: The database server's PostgreSQL extension, such as pgvector, is older than the project's migrations and queries need
• toolchain.artifact_write_failed: A file Jadpo writes for you, such as a record, couldn't be written, usually because it or its folder is read-only
• toolchain.not_built_yet: Operation is declared but not built yet
• toolchain.project_not_found: You ran a command that works on a project in a folder with no app.jadpo, in it or in any folder above it