{"id":34643851,"url":"https://github.com/vvka-141/pgmi","last_synced_at":"2026-02-20T23:14:57.770Z","repository":{"id":330309501,"uuid":"1068458044","full_name":"vvka-141/pgmi","owner":"vvka-141","description":"pgmi — PostgreSQL-native execution fabric. Your SQL drives everything: transactions, execution order, error handling. Session-centric, deterministic, auditable. For humans and autonomous agents.","archived":false,"fork":false,"pushed_at":"2026-02-07T22:30:53.000Z","size":30824,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T02:47:15.947Z","etag":null,"topics":["ai-agents","cli","database-automation","database-migrations","dba-tools","devops","golang","infrastructure-as-code","mcp","plpgsql","postgresql-sql","schema-management","sql","transactional"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vvka-141.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T12:18:19.000Z","updated_at":"2026-02-04T19:38:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vvka-141/pgmi","commit_stats":null,"previous_names":["vvka-141/pgmi"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/vvka-141/pgmi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvka-141%2Fpgmi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvka-141%2Fpgmi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvka-141%2Fpgmi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvka-141%2Fpgmi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vvka-141","download_url":"https://codeload.github.com/vvka-141/pgmi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvka-141%2Fpgmi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29667237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T19:49:36.704Z","status":"ssl_error","status_checked_at":"2026-02-20T19:44:05.372Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","database-automation","database-migrations","dba-tools","devops","golang","infrastructure-as-code","mcp","plpgsql","postgresql-sql","schema-management","sql","transactional"],"created_at":"2025-12-24T17:32:44.906Z","updated_at":"2026-02-20T23:14:57.752Z","avatar_url":"https://github.com/vvka-141.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pgmi\n\n[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)\n[![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go)](https://go.dev/)\n[![CI](https://github.com/vvka-141/pgmi/actions/workflows/ci.yml/badge.svg)](https://github.com/vvka-141/pgmi/actions/workflows/ci.yml)\n[![Watch Introduction](https://img.shields.io/badge/▶_Watch-Introduction-red?logo=youtube)](https://youtu.be/0txwCsGRyyE)\n\npgmi runs your PostgreSQL deployments—but **you** control the transactions, order, and logic.\nUnlike 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.\n\n![pgmi deployment flow](pgmi-deploy.png)\n\n\n## Quick example\n\n```sql\n-- deploy.sql\n-- pg_temp is PostgreSQL's session-scoped schema; your files exist only\n-- for this session and are automatically dropped when it ends.\nBEGIN;\n\nDO $$\nDECLARE\n    v_file RECORD;\nBEGIN\n    FOR v_file IN (\n        SELECT path, content FROM pg_temp.pgmi_source_view\n        WHERE is_sql_file\n        ORDER BY path\n    )\n    LOOP\n        RAISE NOTICE 'Executing: %', v_file.path;\n        EXECUTE v_file.content;\n    END LOOP;\nEND $$;\n\nCOMMIT;\n```\n\n```bash\npgmi deploy ./myapp --database mydb\n```\n\nYour files are in a temp table. You query them with SQL. You decide what to execute. That's the entire model.\n\nThe 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.\n\npgmi 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.\n\n## Install\n\n**macOS / Linux:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/vvka-141/pgmi/main/scripts/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/vvka-141/pgmi/main/scripts/install.ps1 | iex\n```\n\n**Homebrew (macOS/Linux):**\n```bash\nbrew install vvka-141/pgmi/pgmi\n```\n\n**Debian/Ubuntu:**\n```bash\ncurl -1sLf 'https://dl.cloudsmith.io/public/vvka-141/pgmi/setup.deb.sh' | sudo bash\nsudo apt install pgmi\n```\n\n**Go (all platforms):**\n```bash\ngo install github.com/vvka-141/pgmi/cmd/pgmi@latest\n```\n\n## Get started\n\nThe fastest path to your first deployment:\n\n```bash\npgmi init myapp --template basic\ncd myapp\npgmi deploy . --database mydb --overwrite --force\n```\n\nThis creates a project with `deploy.sql`, runs it against a fresh database, and executes the SQL files in `migrations/`.\n\nSee the [Getting Started Guide](docs/QUICKSTART.md) for a complete walkthrough.\n\n## When pgmi makes sense\n\npgmi is a good fit when you need:\n\n- **Conditional deployment logic** — different behavior per environment, feature flags, custom phases\n- **Explicit transaction control** — you decide where `BEGIN` and `COMMIT` go\n- **Full PostgreSQL power** — use PL/pgSQL, query system catalogs, leverage `pg_advisory_lock`\n- **Data files alongside schema** — load JSON config, XML reference data, CSV seeds in the same transaction as migrations\n- **Multi-cloud PostgreSQL targets** — same `deploy.sql` works on Azure, AWS, GCP with native auth (Entra ID, IAM)\n\npgmi handles simple linear migrations out of the box — the basic template does exactly this. Its additional power is there when you need it.\n\nSee [Why pgmi?](docs/WHY-PGMI.md) for a detailed comparison with other tools.\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/QUICKSTART.md) | Your first deployment in 10 minutes |\n| [Why pgmi?](docs/WHY-PGMI.md) | When pgmi's approach makes sense |\n| [Coming from Flyway/Liquibase](docs/COMING-FROM.md) | Migration guides |\n| [deploy.sql Guide](docs/DEPLOY-GUIDE.md) | Authoring patterns: data ingestion, environment branching, multi-phase |\n| [Connections](docs/CONNECTIONS.md) | Connection architecture: cloud auth, SSL, poolers, IaC |\n| [CLI Reference](docs/CLI.md) | All commands, flags, exit codes |\n| [Configuration](docs/CONFIGURATION.md) | pgmi.yaml reference |\n| [Session API](docs/session-api.md) | Temp tables and helper functions |\n| [Testing](docs/TESTING.md) | Database tests with automatic rollback |\n| [Metadata](docs/METADATA.md) | Optional script tracking and ordering |\n| [Security](docs/SECURITY.md) | Secrets and CI/CD patterns |\n| [Production Guide](docs/PRODUCTION.md) | Performance, rollback, monitoring |\n| [Tradeoffs](docs/TRADEOFFS.md) | Honest limitations and who should use pgmi |\n| [MCP Integration](docs/MCP.md) | Model Context Protocol for AI assistants |\n\n## Templates\n\npgmi ships with ready-to-use project templates:\n\n```bash\npgmi templates list              # See available templates\npgmi templates describe basic    # See what a template includes\npgmi init myapp --template basic # Create a project\n```\n\n| Template | Purpose |\n|----------|---------|\n| `basic` | Learning and simple projects. Linear migrations, minimal structure. |\n| `advanced` | Production. Multi-schema, role hierarchy, MCP integration, metadata-driven. |\n\n## AI assistant support\n\npgmi embeds AI-digestible documentation directly in the binary. AI coding assistants (Claude Code, GitHub Copilot, Gemini CLI) can discover and learn pgmi patterns:\n\n```bash\npgmi ai                    # Overview for AI assistants\npgmi ai skills             # List embedded skills\npgmi ai skill pgmi-sql     # Load SQL conventions\n```\n\nWhen you tell an AI assistant \"use pgmi for this project\", it can query these commands to understand pgmi's philosophy, conventions, and best practices.\n\n## Zero-flag deployments\n\nStore connection defaults in `pgmi.yaml`:\n\n```yaml\nconnection:\n  host: localhost\n  database: myapp\n\nparams:\n  env: development\n```\n\nThen deploy with no flags:\n\n```bash\npgmi deploy .\n```\n\nOverride per-environment:\n\n```bash\npgmi deploy . -d staging_db --param env=staging\n```\n\n## Built-in testing\n\nTests live in `__test__/` or `__tests__/` directories. Use the `CALL pgmi_test()` macro in your `deploy.sql` to run them with automatic savepoint isolation:\n\n```sql\n-- deploy.sql\nBEGIN;\n\n-- ... your migrations ...\n\n-- Run tests with automatic savepoint isolation\n-- Each test runs in its own savepoint and rolls back automatically\n-- Test failures raise exceptions, aborting the transaction\nCALL pgmi_test();\n\nCOMMIT;\n```\n\nThe 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.\n\nTests are pure PostgreSQL—use `RAISE EXCEPTION` to fail:\n\n```sql\n-- __test__/test_users.sql\nDO $$\nBEGIN\n    IF NOT EXISTS (SELECT 1 FROM users WHERE email = 'test@example.com') THEN\n        RAISE EXCEPTION 'Expected user not found';\n    END IF;\nEND $$;\n```\n\nSee [Testing Guide](docs/TESTING.md) for fixtures, hierarchical setup, and the gated deployment pattern.\n\n## Authentication\n\npgmi supports:\n\n- **Standard PostgreSQL** — connection strings, `PGPASSWORD`, `.pgpass`\n- **Azure Entra ID** — passwordless auth to Azure Database for PostgreSQL\n- **AWS IAM** — token-based auth to Amazon RDS\n- **Google Cloud SQL IAM** — passwordless auth via Cloud SQL Go Connector\n\n```bash\n# Standard\nexport PGMI_CONNECTION_STRING=\"postgresql://user:pass@localhost/postgres\"\npgmi deploy . -d mydb\n\n# Azure Entra ID — Managed Identity (no credentials needed)\npgmi deploy . --host myserver.postgres.database.azure.com -d mydb --azure --sslmode require\n\n# Azure Entra ID — Service Principal\nexport AZURE_TENANT_ID=\"...\" AZURE_CLIENT_ID=\"...\" AZURE_CLIENT_SECRET=\"...\"\npgmi deploy . --host myserver.postgres.database.azure.com -d mydb --azure --sslmode require\n\n# AWS IAM — uses default credential chain (env vars, ~/.aws/credentials, IAM role)\npgmi deploy . --host mydb.abc123.us-west-2.rds.amazonaws.com -d mydb -U myuser --aws --aws-region us-west-2 --sslmode require\n\n# Google Cloud SQL — uses Application Default Credentials (gcloud auth, service account)\npgmi deploy . -d mydb -U myuser@myproject.iam --google --google-instance myproject:us-central1:myinstance\n```\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[Mozilla Public License 2.0](LICENSE). Template code in `internal/scaffold/templates/` is [MIT licensed](internal/scaffold/templates/LICENSE)—code you generate is yours.\n\nCopyright 2024-2025 Alexey Evlampiev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvka-141%2Fpgmi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvvka-141%2Fpgmi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvka-141%2Fpgmi/lists"}