Advisory Locks

Advisory locks prevent multiple concurrent migrata processes from running migrations on the same database at the same time. They are enabled by default for both the diff (when applying) and apply commands.

How They Work

When a migration runs, the CLI acquires a PostgreSQL session-level advisory lock using pg_try_advisory_lock. This is a non-blocking call:

• If the lock is acquired, the migration proceeds and the lock is released in a finally block when execution completes
• If the lock is not acquired (another process is already running), the CLI prints a warning and exits immediately

What Gets Locked

The advisory lock covers the entire execution of all migration statements, not individual queries. This means the full set of DDL changes are applied atomically from a locking perspective, preventing two CI jobs or CLI instances from stepping on each other.

When to Disable

--skip-lock disables advisory locking entirely. Migrations will run without any coordination. This is useful when:

• You are running migrations against a single-user development database
• You have external locking coordination (e.g., CI pipeline stage gates)
• You are applying read-only or non-conflicting changes

Disabling locks is flagged as unsafe for concurrent runs because two simultaneous migrations could interleave destructive changes.

Usage

migrata apply \
  --from ./migrations/1740612345_add_column.sql \
  --to "postgresql://user:pass@host:5432/mydb" \
  --skip-lock

Or with the diff command:

migrata diff \
  --from ./schemas/current \
  --to ./schemas/target \
  --approve \
  --skip-lock

Dialect Support

Advisory locking uses PostgreSQL-specific pg_try_advisory_lock and pg_advisory_unlock functions. When connecting to other database dialects, advisory locks are automatically skipped.