Troubleshooting & FAQ

Common Issues

"No differences between sources"

The two schemas you are comparing are identical. Make sure you have made changes to the target schema files.

"Docker is not available or running"

The --dev-image flag requires a running Docker daemon. Install Docker Desktop and make sure it is running, or remove the --dev-image flag to skip validation.

"Unsupported scheme" error

Your connection string scheme is not recognized. Supported schemes are postgresql, sqlite, and odbc. Connection strings must use the format scheme://user:pass@host:port/database.

Migration plan shows unexpected changes

The diff command compares the logical structure of two schemas. Make sure you are comparing the correct schemas. Use --include "public*" to restrict the comparison to your main schema and avoid system schemas.

"Cannot use both the --approve and --abort flags"

These flags are mutually exclusive. Use one or the other depending on whether you want to auto-apply or auto-abort.

"Duplicate --answer keys"

Each --answer key must be unique. Check that you are not providing the same key twice.

Advisory lock warning: "Another migration is already running"

Another migrata process is currently running against the same database. Wait for it to complete, or use --skip-lock if you are sure no concurrent migration is in progress.

FAQ

Do I need an account to use migrata?

No. The CLI works immediately after installation with no account required. Authentication is optional.

Can I use migrata in CI/CD pipelines?

Yes. Use --answer to pre-supply responses to interactive prompts and --approve to auto-apply plans. Set --no-styles and --no-logs for clean CI output.

What happens if a migration fails partway through?

The SQL statements are executed sequentially. If a statement fails, the remaining statements are not executed. You should review the error, fix the schema, and re-run.

Does migrata support transactions?

Partition-related changes and safe-cast operations are wrapped in explicit transactions (BEGIN / COMMIT). For regular DDL, PostgreSQL handles most statements as implicit transactions.

Can I roll back a migration?

Migrata generates forward-only migration plans. To roll back, you would generate a reverse diff by swapping the --from and --to sources and apply the resulting plan.

How do I only apply specific tables or schemas?

Use the --include and --exclude flags with glob patterns. For example, --include "public*" limits operations to the public schema.

What image should I use with --dev-image?

Any PostgreSQL Docker image that accepts standard POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment variables. The official postgres images work well (e.g., postgres:16-alpine).