Best Practices

Use the config command

I really can't recommend this one enough, in fact this is the only command I personally used when building the database for this product. You get access to the same commands of the cli, but you can define them inside a config file.

Once you find the right configuration for diffing your database, you can store it in version control. This makes it simple to resuse the command and not worry about forgetting a specific flag or option that breaks your workflow.

To read more about this, visit the config command page

Set the --include property to limit scope

Always set the --include option in the diff and inspect commands. I usually set it to "public*" which matches everything in the public schema. Without it, the tool will scan all schemas in your database.

This has two benefits: it avoids unexpected changes from system schemas appearing in your diff, and it improves performance by reducing the surface area to scan.

Enable the --silent flag

Once you get your schemas synced and validated, assign this flag to the diff and inspect commands. This prevents the tool from outputting parse errors for entities it couldn't parse.

Use the --abort flag for experimentation

When trying out different schema designs, use --abort to see the proposed plans without approving them. This makes it easy to iterate on different configurations without risk of applying changes.

Use --safe-cast in the diff command

When making changes to columns with real data, use --safe-cast to generate non-destructive multi-step SQL:

• Add a new column with the target data type
• Copy and convert data from the old column
• Drop the old column
• Rename the new column to the original name
• Re-apply constraints and indexes

Validate with --dev-image

Before applying to production, test against an ephemeral database using --dev-image. This catches runtime errors from the generated SQL before they reach your live database. See the Dev-Database Validation guide for details.

Automate with --answer

Use --answer to pre-supply responses to interactive planner prompts for fully automated CI/CD runs. Combine with --approve for a completely non-interactive workflow.

Use --skip-lock intentionally

Advisory locks prevent concurrent migrations and are enabled by default. Only disable with --skip-lock when you have external coordination (e.g., single-user dev DB, CI stage gates). See the Advisory Locks guide for details.

Suppress output in CI with --no-logs and --no-styles

In automated environments, use --no-logs to silence progress output and --no-styles to disable console formatting for clean log files.