pgmt 0.4.2

PostgreSQL migration tool that keeps your schema files as the source of truth
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# pgmt — PostgreSQL Schema-as-Code

[![CI](https://github.com/gdpotter/pgmt/actions/workflows/ci.yml/badge.svg)](https://github.com/gdpotter/pgmt/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/pgmt)](https://crates.io/crates/pgmt)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> **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:
```bash
cargo install pgmt
```

Initialize your project:
```bash
# New project
pgmt init

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

Development workflow:
```bash
# 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](https://gdpotter.github.io/pgmt/docs/getting-started/quick-start) — Get up and running
- [Adopt Existing Database](https://gdpotter.github.io/pgmt/docs/guides/existing-database) — Import existing schema with baselines
- [Why Schema-as-Code?](https://gdpotter.github.io/pgmt/docs/concepts/philosophy) — The declarative + explicit approach
- [Schema Organization](https://gdpotter.github.io/pgmt/docs/guides/schema-organization) — Multi-file organization and `-- require:` syntax
- [CLI Reference](https://gdpotter.github.io/pgmt/docs/cli/) — 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](https://gdpotter.github.io/pgmt/docs/reference/supported-features) 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](https://gdpotter.github.io/pgmt/docs/guides/roles-and-permissions).

## Roadmap

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

See the [complete roadmap](https://gdpotter.github.io/pgmt/docs/project/roadmap).

## Development & Contributing

```bash
# 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](https://gdpotter.github.io/pgmt/docs/development/contributing) for more details.

## Community & Support

- [Documentation](https://gdpotter.github.io/pgmt/) — Guides and reference
- [GitHub Discussions](https://github.com/gdpotter/pgmt/discussions) — Questions and patterns
- [GitHub Issues](https://github.com/gdpotter/pgmt/issues) — Bug reports and feature requests

## License

MIT License — see [LICENSE](LICENSE) for details.