# `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. `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.

```text
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

## On every command

- `--json`: Print data for tools instead of text
- `--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

```text
# Write the migration for a new field
jadpo migrate new add_rating
# Finish the latest migration once its decisions are written
jadpo migrate new
# Apply the pending migrations to a database
jadpo migrate apply --url postgresql://localhost/shop
# List the migrations and which a database has applied
jadpo migrate status --url postgresql://localhost/shop
```

## Errors

- [`cli.migrate_arguments`](../errors/cli.migrate_arguments.md): Migrate command has invalid arguments
- [`migration.apply_failed`](../errors/migration.apply_failed.md): Migrations could not be applied
- [`migration.store_diverged`](../errors/migration.store_diverged.md): Database does not match the project's migrations
- [`toolchain.artifact_write_failed`](../errors/toolchain.artifact_write_failed.md): Generated file could not be written
- [`toolchain.not_built_yet`](../errors/toolchain.not_built_yet.md): Operation is declared but not built yet
- [`toolchain.project_not_found`](../errors/toolchain.project_not_found.md): Project could not be found