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.

New to pgmi? Start here:

  1. Quickstart — Deploy your first project
  2. Why pgmi — Understand the philosophy
  3. Session API — Learn the session API
  4. Trade-offs — Understand the honest costs

Migrating from another tool?

  1. Coming from other tools — Flyway, Liquibase, psql migration guides
  2. Quickstart — See pgmi in action

Writing deploy.sql?

  1. deploy.sql guide — Patterns cookbook (data ingestion, environment branching, multi-phase)
  2. Session API — Views, columns, and functions reference

Setting up production?

  1. Connections — Connection architecture (cloud auth, SSL, poolers)
  2. Security — Secrets and CI/CD patterns
  3. CI/CD — Deploy from GitHub Actions and other pipelines
  4. Production — Performance and rollback strategies
  5. CLI reference — All flags and exit codes

Adding tests?

  1. Testing — CALL pgmi_test() and fixtures

Using the advanced template?

  1. Script metadata — Script tracking with <pgmi-meta>
  2. MCP integration — AI assistant integration

Quick Answers#

QuestionAnswer
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 migration scaffold, Advanced = richer reference app — both production-capable; see Quickstart
How do I filter which files run?WHERE clause on pg_temp.pgmi_plan_view — 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)
  • 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 automatic rollback
  • Script metadata — Script tracking with UUIDs, idempotency, sort keys
  • Security — Secrets handling and CI/CD patterns
  • MCP integration — Model Context Protocol for AI assistants

Operations#

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

Recipes (advanced, opt-in)#

  • Semantic MCP curation — Surface the relevant subset of agent tools by embedding similarity (provider-abstracted; 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.

Backward Documentation Why pgmi Forward