https://github.com/vvka-141/pgmi
pgmi — PostgreSQL-native execution fabric. Your SQL drives everything: transactions, execution order, error handling. Session-centric, deterministic, auditable. For humans and autonomous agents.
https://github.com/vvka-141/pgmi
ai-agents cli database-automation database-migrations dba-tools devops golang infrastructure-as-code mcp plpgsql postgresql-sql schema-management sql transactional
Last synced: 30 days ago
JSON representation
pgmi — PostgreSQL-native execution fabric. Your SQL drives everything: transactions, execution order, error handling. Session-centric, deterministic, auditable. For humans and autonomous agents.
- Host: GitHub
- URL: https://github.com/vvka-141/pgmi
- Owner: vvka-141
- License: other
- Created: 2025-10-02T12:18:19.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-07T22:30:53.000Z (about 1 month ago)
- Last Synced: 2026-02-08T02:47:15.947Z (about 1 month ago)
- Topics: ai-agents, cli, database-automation, database-migrations, dba-tools, devops, golang, infrastructure-as-code, mcp, plpgsql, postgresql-sql, schema-management, sql, transactional
- Language: Go
- Homepage:
- Size: 29.4 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# pgmi
[](https://opensource.org/licenses/MPL-2.0)
[](https://go.dev/)
[](https://github.com/vvka-141/pgmi/actions/workflows/ci.yml)
[](https://youtu.be/0txwCsGRyyE)
pgmi runs your PostgreSQL deployments—but **you** control the transactions, order, and logic.
Unlike migration frameworks that decide when to commit and what to run, pgmi loads your files into PostgreSQL temp tables and runs your `deploy.sql`—a script **you** write in SQL that controls the deployment.
## Quick example
```sql
-- deploy.sql
-- pg_temp is PostgreSQL's session-scoped schema; your files exist only
-- for this session and are automatically dropped when it ends.
BEGIN;
DO $$
DECLARE
v_file RECORD;
BEGIN
FOR v_file IN (
SELECT path, content FROM pg_temp.pgmi_source_view
WHERE is_sql_file
ORDER BY path
)
LOOP
RAISE NOTICE 'Executing: %', v_file.path;
EXECUTE v_file.content;
END LOOP;
END $$;
COMMIT;
```
```bash
pgmi deploy ./myapp --database mydb
```
Your files are in a temp table. You query them with SQL. You decide what to execute. That's the entire model.
The quick example above shows the core pattern: query files, execute with `EXECUTE`. The scaffolded templates use `pgmi_plan_view` (which adds metadata-driven ordering) instead of `pgmi_source_view` (raw access). See [Session API](docs/session-api.md) for when to use each.
pgmi loads **all** project files — not just SQL. Your `deploy.sql` can read JSON configuration, XML reference data, and CSV seeds from the same session views, processing them with PostgreSQL's built-in JSON, XML, and string functions. See [deploy.sql Guide](docs/DEPLOY-GUIDE.md) for data ingestion patterns.
## Install
**macOS / Linux:**
```bash
curl -sSL https://raw.githubusercontent.com/vvka-141/pgmi/main/scripts/install.sh | bash
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/vvka-141/pgmi/main/scripts/install.ps1 | iex
```
**Homebrew (macOS/Linux):**
```bash
brew install vvka-141/pgmi/pgmi
```
**Debian/Ubuntu:**
```bash
curl -1sLf 'https://dl.cloudsmith.io/public/vvka-141/pgmi/setup.deb.sh' | sudo bash
sudo apt install pgmi
```
**Go (all platforms):**
```bash
go install github.com/vvka-141/pgmi/cmd/pgmi@latest
```
## Get started
The fastest path to your first deployment:
```bash
pgmi init myapp --template basic
cd myapp
pgmi deploy . --database mydb --overwrite --force
```
This creates a project with `deploy.sql`, runs it against a fresh database, and executes the SQL files in `migrations/`.
See the [Getting Started Guide](docs/QUICKSTART.md) for a complete walkthrough.
## When pgmi makes sense
pgmi is a good fit when you need:
- **Conditional deployment logic** — different behavior per environment, feature flags, custom phases
- **Explicit transaction control** — you decide where `BEGIN` and `COMMIT` go
- **Full PostgreSQL power** — use PL/pgSQL, query system catalogs, leverage `pg_advisory_lock`
- **Data files alongside schema** — load JSON config, XML reference data, CSV seeds in the same transaction as migrations
- **Multi-cloud PostgreSQL targets** — same `deploy.sql` works on Azure, AWS, GCP with native auth (Entra ID, IAM)
pgmi handles simple linear migrations out of the box — the basic template does exactly this. Its additional power is there when you need it.
See [Why pgmi?](docs/WHY-PGMI.md) for a detailed comparison with other tools.
## Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started](docs/QUICKSTART.md) | Your first deployment in 10 minutes |
| [Why pgmi?](docs/WHY-PGMI.md) | When pgmi's approach makes sense |
| [Coming from Flyway/Liquibase](docs/COMING-FROM.md) | Migration guides |
| [deploy.sql Guide](docs/DEPLOY-GUIDE.md) | Authoring patterns: data ingestion, environment branching, multi-phase |
| [Connections](docs/CONNECTIONS.md) | Connection architecture: cloud auth, SSL, poolers, IaC |
| [CLI Reference](docs/CLI.md) | All commands, flags, exit codes |
| [Configuration](docs/CONFIGURATION.md) | pgmi.yaml reference |
| [Session API](docs/session-api.md) | Temp tables and helper functions |
| [Testing](docs/TESTING.md) | Database tests with automatic rollback |
| [Metadata](docs/METADATA.md) | Optional script tracking and ordering |
| [Security](docs/SECURITY.md) | Secrets and CI/CD patterns |
| [Production Guide](docs/PRODUCTION.md) | Performance, rollback, monitoring |
| [Tradeoffs](docs/TRADEOFFS.md) | Honest limitations and who should use pgmi |
| [MCP Integration](docs/MCP.md) | Model Context Protocol for AI assistants |
## Templates
pgmi ships with ready-to-use project templates:
```bash
pgmi templates list # See available templates
pgmi templates describe basic # See what a template includes
pgmi init myapp --template basic # Create a project
```
| Template | Purpose |
|----------|---------|
| `basic` | Learning and simple projects. Linear migrations, minimal structure. |
| `advanced` | Production. Multi-schema, role hierarchy, MCP integration, metadata-driven. |
## AI assistant support
pgmi embeds AI-digestible documentation directly in the binary. AI coding assistants (Claude Code, GitHub Copilot, Gemini CLI) can discover and learn pgmi patterns:
```bash
pgmi ai # Overview for AI assistants
pgmi ai skills # List embedded skills
pgmi ai skill pgmi-sql # Load SQL conventions
```
When you tell an AI assistant "use pgmi for this project", it can query these commands to understand pgmi's philosophy, conventions, and best practices.
## Zero-flag deployments
Store connection defaults in `pgmi.yaml`:
```yaml
connection:
host: localhost
database: myapp
params:
env: development
```
Then deploy with no flags:
```bash
pgmi deploy .
```
Override per-environment:
```bash
pgmi deploy . -d staging_db --param env=staging
```
## Built-in testing
Tests live in `__test__/` or `__tests__/` directories. Use the `CALL pgmi_test()` macro in your `deploy.sql` to run them with automatic savepoint isolation:
```sql
-- deploy.sql
BEGIN;
-- ... your migrations ...
-- Run tests with automatic savepoint isolation
-- Each test runs in its own savepoint and rolls back automatically
-- Test failures raise exceptions, aborting the transaction
CALL pgmi_test();
COMMIT;
```
The macro automatically wraps each test in a savepoint, executes it, and rolls back—so **test data never persists** while your migrations do. If any test fails (via `RAISE EXCEPTION`), the entire transaction aborts and your database remains unchanged.
Tests are pure PostgreSQL—use `RAISE EXCEPTION` to fail:
```sql
-- __test__/test_users.sql
DO $$
BEGIN
IF NOT EXISTS (SELECT 1 FROM users WHERE email = 'test@example.com') THEN
RAISE EXCEPTION 'Expected user not found';
END IF;
END $$;
```
See [Testing Guide](docs/TESTING.md) for fixtures, hierarchical setup, and the gated deployment pattern.
## Authentication
pgmi supports:
- **Standard PostgreSQL** — connection strings, `PGPASSWORD`, `.pgpass`
- **Azure Entra ID** — passwordless auth to Azure Database for PostgreSQL
- **AWS IAM** — token-based auth to Amazon RDS
- **Google Cloud SQL IAM** — passwordless auth via Cloud SQL Go Connector
```bash
# Standard
export PGMI_CONNECTION_STRING="postgresql://user:pass@localhost/postgres"
pgmi deploy . -d mydb
# Azure Entra ID — Managed Identity (no credentials needed)
pgmi deploy . --host myserver.postgres.database.azure.com -d mydb --azure --sslmode require
# Azure Entra ID — Service Principal
export AZURE_TENANT_ID="..." AZURE_CLIENT_ID="..." AZURE_CLIENT_SECRET="..."
pgmi deploy . --host myserver.postgres.database.azure.com -d mydb --azure --sslmode require
# AWS IAM — uses default credential chain (env vars, ~/.aws/credentials, IAM role)
pgmi deploy . --host mydb.abc123.us-west-2.rds.amazonaws.com -d mydb -U myuser --aws --aws-region us-west-2 --sslmode require
# Google Cloud SQL — uses Application Default Credentials (gcloud auth, service account)
pgmi deploy . -d mydb -U myuser@myproject.iam --google --google-instance myproject:us-central1:myinstance
```
## Contributing
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
[Mozilla Public License 2.0](LICENSE). Template code in `internal/scaffold/templates/` is [MIT licensed](internal/scaffold/templates/LICENSE)—code you generate is yours.
Copyright 2024-2025 Alexey Evlampiev