Documentation on pgmi

Overview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Why pgmi

Mon, 01 Jan 0001 00:00:00 +0000

Why pgmi?#

pgmi takes a different approach to database deployments. This document explains when that approach makes sense—and when it doesn’t.

The core idea#

Most deployment tools work like this:

Your files → Tool decides order → Tool decides transactions → Database

pgmi works like this:

Your files → PostgreSQL temp tables → YOUR deploy.sql decides everything → Database

The difference: you write the deployment logic in SQL, not configuration.

A concrete example#

Suppose you need environment-specific deployment behavior:

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with pgmi#

This guide takes you from zero to a working deployment in about 10 minutes. The commands are concrete — the only values you supply are your local PostgreSQL password and the database name.

What you’ll do:

Install pgmi
Make sure PostgreSQL is reachable
Create a project
Deploy it
Verify the deployment

What you need:

PostgreSQL running on localhost:5432 (the default), reachable over a direct connection or a session-mode pooler — transaction-mode poolers (PgBouncer txn mode, RDS Proxy) break pgmi’s session temp tables; see Connection Requirements
A PostgreSQL user with database creation rights (typically postgres)

No Go toolchain required — the quickstart installs a prebuilt binary. (Installing from source with go install is an optional alternative; see Step 1.)

Coming from other tools

Mon, 01 Jan 0001 00:00:00 +0000

Coming from Other Tools#

This guide helps you migrate to pgmi from other database deployment tools. Each section maps familiar concepts to pgmi equivalents and shows a concrete migration path.

How pgmi deploys: The deploy.sql examples below query files from pg_temp.pgmi_plan_view (or pg_temp.pgmi_source_view) and execute them directly with EXECUTE. See Session API for the full reference.

Quick concept mapping#

Concept	Flyway	Liquibase	pgmi
Migration files	`V1__name.sql`	Changelog + changesets	Any `.sql` file
Execution order	Filename prefix (V1, V2…)	Changelog order	Your `deploy.sql` decides
Transaction control	`flyway.group=true` (batch)	Per-changeset or global	`BEGIN`/`COMMIT` in deploy.sql
Tracking state	`flyway_schema_history` table	`databasechangelog` table	Your choice (or none)
Rollback	Undo scripts (`U1__name.sql`)	Rollback commands in changeset	PostgreSQL transactions
Conditionals	Callbacks, limited	Preconditions, contexts	Full PL/pgSQL in deploy.sql
Configuration	`flyway.conf` / `flyway.toml`	`liquibase.properties`	`pgmi.yaml`

Coming from Flyway#

What changes#

Before (Flyway):

CLI reference

Mon, 01 Jan 0001 00:00:00 +0000

CLI Reference#

Complete reference for all pgmi commands. Every example is copy-paste ready.

For a guided walkthrough, see Quickstart .

Global Flags#

These flags work with every command:

Flag	Description
`-v, --verbose`	Enable verbose output (also shows PostgreSQL `RAISE DEBUG` messages)
`-h, --help`	Show help for any command

pgmi deploy#

Execute a database deployment.

pgmi deploy <project_path> [flags]

pgmi connects to PostgreSQL, loads your project files into session temp tables, then runs deploy.sql which directly executes your files.

Connections

Mon, 01 Jan 0001 00:00:00 +0000

Connection Architecture#

How pgmi connects to every PostgreSQL target — from localhost to multi-cloud managed services.

For CLI flag details, see CLI reference . For CI/CD pipeline examples, see Production .

Connection provider factory#

pgmi resolves CLI flags and environment variables into a concrete connector at startup:

Auth method	Connector	How tokens work
Standard	`StandardConnector`	Username/password via pgx, with retry (3 attempts, exponential backoff)
Azure Entra ID	`TokenBasedConnector`	`azidentity.NewDefaultAzureCredential` chain, OAuth token as password
AWS IAM	`TokenBasedConnector`	`rds/auth.BuildAuthToken` via default AWS credential chain
Google Cloud SQL IAM	`GoogleCloudSQLConnector`	`cloud.google.com/go/cloudsqlconn` with IAM auth and internal TLS

All providers produce a *pgx.Conn — the rest of pgmi doesn’t know or care which auth method was used.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration Reference (pgmi.yaml)#

Overview#

pgmi.yaml is an optional project-level configuration file that stores connection defaults and parameters. Place it in your project root (next to deploy.sql) to enable zero-flag deployments:

# Instead of:
pgmi deploy . --database myapp --param env=development

# Just:
pgmi deploy .

pgmi init generates a pgmi.yaml automatically for both templates.

Coming from Other Tools#

Tool	Config File	pgmi Equivalent
Flyway	`flyway.conf`	`pgmi.yaml`
.NET EF Core	`appsettings.json`	`pgmi.yaml`
Prisma	`schema.prisma`	`pgmi.yaml`
Liquibase	`liquibase.properties`	`pgmi.yaml`

Key difference: pgmi.yaml configures the runner (connection, parameters, timeout). Deployment logic lives in deploy.sql, not in configuration.

deploy.sql guide

Mon, 01 Jan 0001 00:00:00 +0000

deploy.sql Authoring Guide#

This guide covers patterns for writing deploy.sql — from basic file execution to data ingestion, environment branching, and multi-phase deployments. Every example is copy-paste ready.

For the session API reference (views, columns, functions), see Session API .

The basic pattern#

Your deploy.sql queries files from session views and executes them with EXECUTE:

BEGIN;

DO $$
DECLARE v_file RECORD;
BEGIN
 FOR v_file IN (
 SELECT path, content
 FROM pg_temp.pgmi_source_view
 WHERE directory = './migrations/' AND is_sql_file
 ORDER BY path
 ) LOOP
 RAISE NOTICE 'Executing: %', v_file.path;
 EXECUTE v_file.content;
 END LOOP;
END $$;

COMMIT;

Use pgmi_plan_view instead of pgmi_source_view when you want metadata-driven ordering via <pgmi-meta> blocks. See Session API .

Script metadata

Mon, 01 Jan 0001 00:00:00 +0000

Script Metadata Guide#

pgmi supports optional XML metadata blocks in SQL files that control deployment behavior: path-independent tracking, idempotency control, and explicit execution ordering.

Metadata is Optional#

You don’t need metadata to use pgmi.

The basic template works perfectly without any metadata. Files execute in lexicographic path order, and pgmi generates deterministic fallback identifiers from file paths.

myproject/
├── deploy.sql # No metadata needed
├── migrations/
│ ├── 001_users.sql # No metadata needed
│ └── 002_orders.sql # No metadata needed
└── __test__/
 └── test_users.sql # No metadata needed

This is often sufficient. Add metadata only when you need its specific capabilities.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Database Testing with pgmi#

This guide teaches you how to test your PostgreSQL code using pgmi — from your first test to hierarchical fixtures. Every example is copy-paste ready.

The problem pgmi solves#

Testing database code is hard because changes persist. If a test creates a table, that table exists for the next test. If a test inserts rows, those rows are visible to every test that follows. Tests become order-dependent, flaky, and impossible to run in isolation.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Security Guide#

pgmi handles sensitive parameters (passwords, API keys, tokens) as part of database deployments. This guide covers pgmi’s security model, known threat vectors, and recommended practices for CI/CD pipelines.

API keys: the advanced template ships a machine-to-machine API key subsystem (membership.api_key, SHA-256-hashed, hash-safe compare, SECURITY DEFINER lifecycle). See API keys .

Required Permissions#

Operation	Minimum Privilege
`pgmi deploy` (new database)	`CREATEDB` on the PostgreSQL cluster
`pgmi deploy` (existing database)	`CREATE` on `pg_temp` schema (granted by default to all roles)
DDL in migrations	Depends on your SQL — typically schema owner or `CREATE` on target schema
Advanced template role setup	`CREATEROLE` + `CREATE EXTENSION` (initial setup only — no superuser)

pgmi itself only needs to: connect, create temp tables (automatic for any role), set session variables, and execute your deploy.sql. The actual permissions depend on what your SQL does.

Production

Mon, 01 Jan 0001 00:00:00 +0000

Production Guide#

This guide covers considerations for running pgmi in production environments: performance, rollback strategies, monitoring, and operational patterns.

Connection requirements#

pgmi requires a direct PostgreSQL connection or a connection pooler in session mode.

pgmi uses session-scoped temporary tables (pg_temp) that exist only for the lifetime of a single database connection. Connection poolers in transaction or statement mode reassign connections between operations, destroying the temporary tables mid-deployment.

Pooler Mode	Compatible	Why
Session	Yes	Connection stays with one backend for the entire session
Transaction	No	Backend may change between transactions — `pg_temp` state lost
Statement	No	Backend may change between statements — `pg_temp` state lost

This applies to PgBouncer, Pgpool-II, AWS RDS Proxy, Azure PgBouncer, and any other connection pooler. Direct connections are always safe. If you use a pooler, either configure session mode for pgmi deployments or bypass the pooler with a direct connection string.

CI/CD

Mon, 01 Jan 0001 00:00:00 +0000

CI/CD#

Deploy pgmi projects from any CI system. The pattern is always the same: install a pinned pgmi binary, point it at a direct database connection via secrets, and run pgmi deploy with a pinned API version.

Requirements#

A direct PostgreSQL connection (or a session-mode pooler). Transaction-mode poolers — PgBouncer in transaction mode, AWS RDS Proxy, Azure’s built-in PgBouncer — reassign connections between statements and destroy the session-scoped temp tables pgmi relies on. See Connection Requirements .
Secrets from your CI secret store, never on the command line. See the Security Guide .

GitHub Actions#

name: Deploy database

on:
 push:
 branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest
 env:
 PGMI_VERSION: v0.11.0  # pin to a specific release tag
 DB_NAME: myapp
 steps:
 - uses: actions/checkout@v4

 - name: Install pgmi (pinned, checksum-verified)
 run: |
 file="pgmi_${PGMI_VERSION#v}_linux_amd64.tar.gz"
 base="https://github.com/vvka-141/pgmi/releases/download/${PGMI_VERSION}"
 curl -fsSLO "${base}/${file}"
 curl -fsSLO "${base}/checksums.txt"
 sha256sum --ignore-missing -c checksums.txt
 tar -xzf "${file}" pgmi
 sudo install pgmi /usr/local/bin/pgmi
 pgmi --version

 - name: Deploy
 env:
 PGMI_CONNECTION_STRING: ${{ secrets.DATABASE_URL }}  # direct connection
 run: pgmi deploy . -d "$DB_NAME" --compat 1 --force

Why these choices:

MCP integration

Mon, 01 Jan 0001 00:00:00 +0000

Model Context Protocol (MCP) Integration#

pgmi’s advanced template includes a complete MCP server implementation, enabling AI assistants (Claude Desktop, VS Code Copilot, etc.) to interact with your PostgreSQL database through tools, resources, and prompts.

Overview#

The Model Context Protocol (MCP) is an open standard that allows AI applications to connect to external systems. pgmi implements MCP entirely in PostgreSQL, with a thin HTTP gateway for transport.

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────────┐
│ AI Client │────▶│ HTTP Gateway │────▶│ PostgreSQL │
│ (Claude, etc.) │ │ (Python/Go) │ │ │
│ │◀────│ │◀────│ api.mcp_handle_request() │
└─────────────────┘ └─────────────────┘ │ ├── tools (execute actions) │
 │ ├── resources (read data) │
 │ └── prompts (message templates)│
 └─────────────────────────────────┘

Quick Start#

1. Deploy the Advanced Template#

pgmi init --template advanced myproject
cd myproject
pgmi deploy --connection "postgresql://user:pass@localhost:5432/mydb"

2. Start the HTTP Gateway#

The pgmi init --template advanced command generates a tools/ directory with the Python gateway:

API keys

Mon, 01 Jan 0001 00:00:00 +0000

API Key Authentication#

Machine-to-machine authentication for agents, MCP clients, and CI pipelines. Ships with the advanced template in membership/08-api-keys.sql.

Key format#

{prefix}_{key_id}_{secret}

prefix — short tenant-configurable label (default pgmi), sourced from the pgmi.api_key_prefix GUC. Set via ALTER DATABASE mydb SET pgmi.api_key_prefix = 'myapp' or --param api_key_prefix=myapp on deploy.
key_id — 8-char alphanumeric identifier stored unhashed for O(1) lookup. Never secret on its own.
secret — 32 bytes of random material encoded as URL-safe base64.

Only SHA-256(full_key) is persisted. The raw key is returned exactly once, at creation, and never recoverable.

Session API

Mon, 01 Jan 0001 00:00:00 +0000

pgmi Session API Reference#

Core model: pgmi doesn’t interpret your SQL — it loads your files into PostgreSQL session tables and hands control to deploy.sql, which decides what to do with them.

How pgmi Actually Works#

When you run pgmi deploy ./myproject, here’s what happens:

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. CONNECT │
│ pgmi connects to PostgreSQL │
└────────────────────────────────────────────┬────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. PREPARE SESSION │
│ pgmi creates temporary tables and views (two-tier API): │
│ │
│ Internal tables: _pgmi_source, _pgmi_parameter, _pgmi_source_metadata│
│ _pgmi_test_source, _pgmi_test_directory │
│ Public views: pgmi_source_view, pgmi_parameter_view, pgmi_plan_view│
│ pgmi_source_metadata_view │
│ pgmi_test_source_view, pgmi_test_directory_view │
│ │
│ If --verbose: SET client_min_messages = 'debug' (enables RAISE DEBUG)│
│ Functions: pgmi_test_plan(), pgmi_test_generate() │
└────────────────────────────────────────────┬────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. EXECUTE deploy.sql │
│ YOUR deploy.sql runs and directly executes files using: │
│ │
│ FOR v_file IN (SELECT * FROM pgmi_plan_view ORDER BY execution_order)│
│ LOOP │
│ EXECUTE v_file.content; │
│ END LOOP; │
│ │
│ Transaction boundaries, error handling, execution order—all yours. │
└─────────────────────────────────────────────────────────────────────────┘

The key insight: deploy.sql is the deployment script. It queries pgmi_plan_view and uses EXECUTE to run files directly. You control the deployment logic — transactions, ordering, conditionals, error handling.

Trade-offs

Mon, 01 Jan 0001 00:00:00 +0000

Honest Limitations#

pgmi trades framework-managed complexity for SQL-level control. That trade has real costs. This page lists them honestly so you can decide if they apply to your team and project.

PL/pgSQL expertise required#

pgmi’s deploy.sql is a PL/pgSQL program, not configuration. Your team needs to be comfortable with:

FOR v_file IN (SELECT ...) LOOP ... END LOOP
EXECUTE v_file.content
BEGIN ... EXCEPTION WHEN OTHERS THEN ... END
current_setting('pgmi.key', true)

Honest test: If your team would struggle to write a PL/pgSQL function that loops over a query result, calls EXECUTE on each row, and handles exceptions — pgmi’s power is inaccessible. The basic template works out of the box, but customizing deployment logic requires PL/pgSQL fluency.

Documentation on pgmi

Overview

pgmi Documentation#

Recommended Reading Order#

Why pgmi

Why pgmi?#

The core idea#

A concrete example#

Quickstart

Getting Started with pgmi#

Coming from other tools

Coming from Other Tools#

Quick concept mapping#

Coming from Flyway#

What changes#

CLI reference

CLI Reference#

Global Flags#

pgmi deploy#

Connections

Connection Architecture#

Connection provider factory#

Configuration

Configuration Reference (pgmi.yaml)#

Overview#

Coming from Other Tools#

deploy.sql guide

deploy.sql Authoring Guide#

The basic pattern#

Script metadata

Script Metadata Guide#

Metadata is Optional#

Testing

Database Testing with pgmi#

The problem pgmi solves#

Security

Security Guide#

Required Permissions#

Production

Production Guide#

Connection requirements#

CI/CD

CI/CD#

Requirements#

GitHub Actions#

MCP integration

Model Context Protocol (MCP) Integration#

Overview#

Quick Start#

1. Deploy the Advanced Template#

2. Start the HTTP Gateway#

API keys

API Key Authentication#

Key format#

Session API

pgmi Session API Reference#

How pgmi Actually Works#

Trade-offs

Honest Limitations#

PL/pgSQL expertise required#