Getting Help

Debugging

When something isn’t working as expected:

# See what pgmt is doing
pgmt apply --verbose

# Full debug output
pgmt apply --debug

# Preview without making changes
pgmt apply --dry-run

For migration issues:

# Check if migrations are consistent with schema
pgmt migrate validate

# See what's different between schema files and database
pgmt diff

For dependency ordering issues:

# Analyze the dependency graph
pgmt debug dependencies

# Focus on a specific object
pgmt debug dependencies --object public.users

# Human-readable format
pgmt debug dependencies --format text

If pgmt baseline create or pgmt migrate new fails with ordering errors, use the debug command to inspect which objects depend on which, and add -- require: headers to your schema files as needed.

Common Setup Issues

Can’t connect to database:

# Is PostgreSQL running?
pg_isready -h localhost -p 5432

# Does the database exist?
createdb myapp_dev

Shadow database creation fails:

Your user needs CREATEDB privilege. Or configure a manual shadow database:

pgmt.yaml

databases:
  shadow:
    auto: false
    url: postgres://localhost/myapp_shadow

Reporting Issues

When opening an issue on GitHub, include:

• pgmt version (pgmt --version)
• PostgreSQL version (psql --version)
• Full error output
• Steps to reproduce

Links

• GitHub Issues - Bug reports
• GitHub Discussions - Questions
• pgmt --help or pgmt <command> --help - CLI reference