tcb db pg migration up
Apply pending local migrations. The command builds an execution plan, submits the job, and polls until the job finishes.
Usage
tcb db pg migration up -e <envId> [--dry-run] [--include-all]
Parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
--dry-run | No | Preview the execution plan without applying it | false |
--include-all | No | Allow pending migrations whose version is older than the latest remote version | false |
-e, --env-id <envId> | Yes | Environment ID | — |
--json | No | Output JSON | — |
Examples
# Preview pending migrations only
tcb db pg migration up -e <envId> --dry-run
# Apply migrations
tcb db pg migration up -e <envId>
# Allow out-of-order migrations, used when a local version is older than the latest online version
tcb db pg migration up -e <envId> --include-all
Full workflow
# 1. First-time onboarding: pull all historical remote migrations
tcb db pg migration fetch -e <envId>
# 2. Add a change: create a migration file and edit it
tcb db pg migration new create_orders_table
# Edit cloudbase/migrations/<version>_create_orders_table.sql and write the SQL
# 3. Preview the execution plan
tcb db pg migration up -e <envId> --dry-run
# 4. Apply
tcb db pg migration up -e <envId>
# 5. Check the status
tcb db pg migration list -e <envId>
Declarative execution
Configure the database field in cloudbaserc.json to run migrations through tcb deploy.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | String | Yes | — | Database type, currently postgresql only |
migrations | String | No | ./cloudbase/migrations | Migration file directory, relative to the project directory, relative paths only |
{
"database": {
"type": "postgresql",
"migrations": "./cloudbase/migrations"
}
}
The CLI executes files in ascending lexicographic order. Applied files are recorded in the __migrations table and are not executed again. See Configuration file for every field.
Notes
- Declarative migrations do not support automatic rollback, write the reverse SQL manually
migration repair --status revertedmarks the history record only and does not revert SQL changes