pgmt — PostgreSQL Schema-as-Code

Database-first development for PostgreSQL Manage schema like code, deploy through explicit migrations

Status: Alpha — API may change. Production use requires careful evaluation.

pgmt is a PostgreSQL migration tool that lets you develop your schema like software code — edit database objects directly, see changes immediately, then generate explicit migrations for production deployment.

Key Benefits

• Code-like Development: Edit views, functions, triggers, and grants like source code — pgmt handles drop/recreate automatically
• Explicit Control: Review generated migrations before deployment, not after
• Full PostgreSQL Support: Triggers, functions, enums, arrays, JSON, extensions, grants — not just tables
• Team Friendly: Schema files show intent, migrations show deployment steps
• Production Safe: Shadow databases, dependency ordering, sectioned migrations

Why pgmt?

Unlike migration-only tools (Flyway, golang-migrate) where you write every migration by hand, or fully declarative tools that hide migrations entirely, pgmt combines both: write your schema declaratively, then review and control the explicit migrations it generates.

Requirements

• PostgreSQL 13+ (tested on PostgreSQL 13, 14, 15, 16, 17, 18)
• Rust 1.74+ for building from source

Quick Start

Install pgmt:

cargo install pgmt

Initialize your project:

# New project
pgmt init

# From existing database
pgmt init --dev-url postgres://localhost/my_existing_db

Development workflow:

# 1. Edit schema files like code
vim schema/views/user_analytics.sql
vim schema/functions/calculate_score.sql

# 2. Apply immediately to dev database
pgmt apply

# 3. Generate migration when ready
pgmt migrate new "add user analytics"

# 4. Deploy to production
pgmt migrate apply --target-url $PROD_DATABASE_URL

Documentation

• Quick Start — Get up and running
• Adopt Existing Database — Import existing schema with baselines
• Why Schema-as-Code? — The declarative + explicit approach
• Schema Organization — Multi-file organization and -- require: syntax
• CLI Reference — All commands and options

PostgreSQL Support

Core Objects: Tables, Views, Functions, Triggers, Indexes, Constraints, Custom Types, Sequences, Schemas, Extensions Advanced Features: Grants & Privileges, Row-Level Security, Comments, Complex Constraints, All Index Types, Function Overloading PostgreSQL-Specific: ENUMs, Arrays, JSON/JSONB, Exclusion Constraints, Partial Indexes, Expression Indexes

See the complete feature matrix for details.

Role & Permissions Management

pgmt manages database object privileges (GRANT/REVOKE) but not roles themselves — create roles using your preferred tools (SQL, Terraform, etc.), then define grants in schema files.

See the Roles & Permissions Guide.

Roadmap

Near-term: Advanced function features, smart rename detection, materialized views Long-term: Schema visualization, migration templates

See the complete roadmap.

Development & Contributing

# Quick setup (one-time)
./scripts/test-setup.sh

# Run tests
cargo test

# Test against specific PostgreSQL version
DATABASE_URL=$(./scripts/test-db-url.sh 18) cargo test

# Build from source
SQLX_OFFLINE=true cargo build

See the contributing guide for more details.

Community & Support

• Documentation — Guides and reference
• GitHub Discussions — Questions and patterns
• GitHub Issues — Bug reports and feature requests

License

MIT License — see LICENSE for details.