pgmi Documentation#

pgmi is a PostgreSQL-native deployment tool that loads your project files into session temp tables and lets your deploy.sql drive everything — transactions, execution order, and logic. These docs cover the session API, CLI, deployment patterns, testing, security, and operational guides.

The pgmi model: pgmi prepares one PostgreSQL session and hands control to your deploy.sql

Quick Answers#

Question	Answer
Which view should I use?	`pgmi_plan_view` for deployment, `pgmi_source_view` for introspection — see Session API
How do I access CLI parameters?	`current_setting('pgmi.key', true)` — see Session API
How do I run tests?	`CALL pgmi_test()` in deploy.sql — see Testing
What’s the difference between templates?	Basic = small, explicit migration scaffold. Advanced = ~19k lines of tested SQL application stack (one handler registry → REST+RPC+MCP+OpenAPI, RLS auth, transaction policy, audit trails) — more infrastructure, not a higher safety tier. Either is production-capable; see Quickstart and the capability tour
How do I filter which files run?	Join `pgmi_plan_view` to `pgmi_source_view`, require `is_sql_file`, then add your path filter — see Session API
What exit codes does pgmi use?	0=success, 13=SQL error, etc. — see CLI reference

All Documentation#

Getting Started#

Quickstart — Your first deployment (install, configure, deploy, verify)
Why pgmi — When pgmi’s approach makes sense (and when it doesn’t)
Core vs. template — The boundary between pgmi core and your scaffolded project
Highlights — Ten distinctive pgmi capabilities, grounded in code and guides
Coming from other tools — Migration guides from Flyway, Liquibase, and raw psql

Reference#

CLI reference — Complete CLI reference (commands, flags, exit codes, error messages)
Configuration — pgmi.yaml schema and precedence rules
Session API — Session views and functions (pg_temp.pgmi_*)

Guides#

deploy.sql guide — deploy.sql authoring patterns (data ingestion, environment branching, multi-phase)
Connections — Connection architecture (cloud auth, SSL, poolers, IaC)
Trade-offs — Honest limitations and who should use pgmi

Features#

Testing — Database testing with savepoint isolation and deploy gates
Script metadata — Script tracking with UUIDs, idempotency, sort keys
Security — Secrets handling and CI/CD patterns

Operations#

CI/CD — Deploy from GitHub Actions and other pipelines
Production — Performance, rollback strategies, monitoring

Advanced template (~19k lines you own)#

These pages document application code scaffolded by pgmi init --template advanced — a complete PostgreSQL application stack, not a pgmi core feature. The generated SQL and gateways become code you own, modify, or delete. Start at the capability tour .

MCP gateway — Expose your deployed application’s tools, resources, and prompts to AI assistants over HTTP
API keys — API key authentication for callers of your generated REST/RPC/MCP APIs
Client guides — Generate typed clients from your deployment’s OpenAPI contract
Transaction policy — Per-route isolation floor, read-only declaration, DEFERRABLE derivation, fail-closed enforcement, replica-safe hint
MCP gateway — Gateway internals: routing, auth, transaction lifecycle, OpenAPI generation
MCP handlers — Authoring MCP tool/resource/prompt handlers
MCP protocol — JSON-RPC wire protocol and session lifecycle
MCP SQL API — SQL functions powering the MCP gateway
Semantic MCP curation — Optional extension to the MCP gateway: surface the relevant tool subset by embedding similarity (for tool-overload scale)

AI Integration#

pgmi ai                    # Overview for AI assistants
pgmi ai skills             # List embedded skills
pgmi ai skill pgmi-sql     # Load SQL conventions

See CLI.md#pgmi-ai for details.