{"id":39760740,"url":"https://github.com/constructive-io/pgpm-modules","last_synced_at":"2026-01-18T11:37:41.642Z","repository":{"id":324511186,"uuid":"1097477045","full_name":"constructive-io/pgpm-modules","owner":"constructive-io","description":"PostgreSQL modules using the pgpm workflow for safe, testable, reversible SQL changes.","archived":false,"fork":false,"pushed_at":"2026-01-14T01:35:49.000Z","size":6563,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T04:42:38.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/constructive-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-16T08:56:18.000Z","updated_at":"2026-01-14T01:35:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/constructive-io/pgpm-modules","commit_stats":null,"previous_names":["launchql/pgpm-modules","constructive-io/pgpm-modules"],"tags_count":1376,"template":false,"template_full_name":null,"purl":"pkg:github/constructive-io/pgpm-modules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Fpgpm-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Fpgpm-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Fpgpm-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Fpgpm-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/constructive-io","download_url":"https://codeload.github.com/constructive-io/pgpm-modules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Fpgpm-modules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28535169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"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":[],"created_at":"2026-01-18T11:37:40.956Z","updated_at":"2026-01-18T11:37:41.609Z","avatar_url":"https://github.com/constructive-io.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pgpm modules\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003cimg height=\"250\" src=\"https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003ca href=\"https://github.com/constructive-io/pgpm-modules/actions/workflows/ci.yml\"\u003e\n    \u003cimg height=\"20\" src=\"https://github.com/constructive-io/pgpm-modules/actions/workflows/ci.yml/badge.svg\" /\u003e\n  \u003c/a\u003e\n   \u003ca href=\"https://github.com/constructive-io/pgpm-modules/blob/main/LICENSE\"\u003e\u003cimg height=\"20\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nPostgreSQL modules using the `pgpm` workflow for safe, testable, reversible SQL changes.\n\n## Overview\n\n**pgpm** is a modern CLI for modular PostgreSQL development—a focused command-line tool for PostgreSQL database migrations and package management. It provides the core functionality for managing database schemas, migrations, and module dependencies.\n\nThis repository contains a curated collection of PostgreSQL modules built using the `pgpm` workflow. Each module follows the Sqitch-inspired deploy/verify/revert pattern, extending it to a multi-package npm workspace where SQL changes are organized as triplets, enabling safe database migrations with proper rollback capabilities.\n\n### Key Features\n\n- 📦 **Postgres Module System** — Reusable, composable database packages with dependency management, per-module plans, and versioned releases\n- 🔄 **Deterministic Migration Engine** — Version-controlled, plan-driven deployments with rollback support and idempotent execution enforced by dependency and validation safeguards\n- 📊 **Recursive Module Resolution** — Recursively resolves database package dependencies (just like npm) from plan files or SQL headers, producing a reproducible cross-module migration graph\n- 🏷️ **Tag-Aware Versioning** — Deploy to @tags, resolve tags to changes, and reference tags across modules for coordinated releases\n- 🐘 **Portable Postgres Development** — Rely on standard SQL migrations for a workflow that runs anywhere Postgres does\n\n## Installation\n\n```bash\n# Install pgpm CLI \nnpm install -g pgpm\n```\n\n## Using These Modules\n\nAll modules in this repository are published to npm under the `@pgpm` scope. Install and use them in your own pgpm projects.\n\n### 🚀 Quick Start\n\n#### Setup Your Environment\n\n```bash\n# Start local Postgres (via Docker) and export env vars\npgpm docker start\neval \"$(pgpm env)\"\n```\n\n\u003e **Tip:** Already running Postgres? Skip the Docker step and just export your `PG*` environment variables.\n\n#### Create a Workspace and Install a Package\n\n```bash\n# 1. Create a workspace\npgpm init workspace\n\n# 2. Create your first module\ncd my-workspace\npgpm init\n\n# 3. Install a package\ncd packages/my-module\npgpm install @pgpm/faker\n\n# 4. Deploy everything\npgpm deploy --createdb --database mydb1\npsql -d mydb1 -c \"SELECT faker.city('MI');\"\n\u003e  Ann Arbor\n```\n\n#### Add to an Existing Module\n\n```bash\n# 1. Navigate to your module\ncd packages/my-module\n\n# 2. Install a package\npgpm install @pgpm/faker\n\n# 3. Deploy all installed modules\npgpm deploy --createdb --database mydb1\npsql -d mydb1 -c \"SELECT faker.city('MI');\"\n\u003e  Sterling Heights\n```\n\n#### Add a Database Change\n\n```bash\n# 1. Navigate to your module\ncd packages/my-module\n\n# 2. Add a database change\npgpm add some_change\n```\n\n#### Testing your Database\n\n```bash\n# 1. Navigate to your module\ncd packages/my-module\n\n# 2. Add a database change\npnpm test:watch\n```\n\nEach module includes its own README with detailed documentation. See individual package directories for usage examples and API documentation.\n\n---\n\n## Package Structure\n\n### Data Types\n- [`@pgpm/types`](https://www.npmjs.com/package/@pgpm/types) - Core PostgreSQL data types\n- [`@pgpm/uuid`](https://www.npmjs.com/package/@pgpm/uuid) - UUID utilities and extensions\n- [`@pgpm/stamps`](https://www.npmjs.com/package/@pgpm/stamps) - Timestamp utilities and audit trails\n- [`@pgpm/geotypes`](https://www.npmjs.com/package/@pgpm/geotypes) - Geographic data types and spatial functions\n\n### Jobs \u0026 Background Processing\n- [`@pgpm/jobs`](https://www.npmjs.com/package/@pgpm/jobs) - Core job system for background tasks\n- [`@pgpm/database-jobs`](https://www.npmjs.com/package/@pgpm/database-jobs) - Database-specific job handling\n\n### Meta \u0026 Database Introspection\n- [`@pgpm/metaschema-schema`](https://www.npmjs.com/package/@pgpm/metaschema-schema) - Database metadata schema and utilities\n- [`@pgpm/metaschema-modules`](https://www.npmjs.com/package/@pgpm/metaschema-modules) - Module metadata handling\n- [`@pgpm/services`](https://www.npmjs.com/package/@pgpm/services) - Services schemas for APIs, sites, and domains\n\n### Security \u0026 Authentication\n- [`@pgpm/defaults`](https://www.npmjs.com/package/@pgpm/defaults) - Security defaults and configurations\n- [`@pgpm/jwt-claims`](https://www.npmjs.com/package/@pgpm/jwt-claims) - JWT claim handling and validation\n- [`@pgpm/totp`](https://www.npmjs.com/package/@pgpm/totp) - Time-based One-Time Password authentication\n- [`@pgpm/encrypted-secrets`](https://www.npmjs.com/package/@pgpm/encrypted-secrets) - Encrypted secrets management\n- [`@pgpm/encrypted-secrets-table`](https://www.npmjs.com/package/@pgpm/encrypted-secrets-table) - Table-based encrypted secrets\n\n### Utilities\n- [`@pgpm/utils`](https://www.npmjs.com/package/@pgpm/utils) - General utility functions\n- [`@pgpm/verify`](https://www.npmjs.com/package/@pgpm/verify) - Verification utilities (used by other modules)\n- [`@pgpm/inflection`](https://www.npmjs.com/package/@pgpm/inflection) - String inflection utilities\n- [`@pgpm/base32`](https://www.npmjs.com/package/@pgpm/base32) - Base32 encoding/decoding\n- [`@pgpm/faker`](https://www.npmjs.com/package/@pgpm/faker) - Fake data generation for testing\n\n### Metrics \u0026 Analytics\n- [`@pgpm/measurements`](https://www.npmjs.com/package/@pgpm/measurements) - Performance tracking and analytics\n- [`@pgpm/achievements`](https://www.npmjs.com/package/@pgpm/achievements) - Achievement system for user progress\n\n## pgpm Workflow\n\nEach package follows the Sqitch-inspired **deploy/verify/revert** pattern:\n\n- **Deploy**: `deploy/**/*.sql` - Applies database changes\n- **Verify**: `verify/**/*.sql` - Proves changes work correctly\n- **Revert**: `revert/**/*.sql` - Safely removes changes\n\n## Developing\n\nThis section is for **contributing to** or **developing** the modules in this repository. If you just want to use the published modules, see [Using These Modules](#using-these-modules) above.\n\n### Getting Started\n\n```bash\n# Clone the repository\ngit clone https://github.com/constructive-io/pgpm-modules.git\ncd pgpm-modules\n\n# Install dependencies\npnpm install\n```\n\n### Testing a Package\n\n```bash\n# 1. Install workspace deps\npnpm install\n\n# 2. Enter the module directory\ncd packages/utils/base32\n\n# 3. Run tests in watch mode\npnpm test:watch\n```\n\n### Publishing\n\n```bash\n# Publish to npm\npnpm lerna publish\n```\n\n## Related Tooling\n\n* [pgpm](https://github.com/constructive-io/constructive/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.\n* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.\n* [supabase-test](https://github.com/constructive-io/constructive/tree/main/packages/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.\n* [graphile-test](https://github.com/constructive-io/constructive/tree/main/packages/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.\n* [pgsql-parser](https://github.com/constructive-io/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.\n* [libpg-query-node](https://github.com/constructive-io/libpg-query-node): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.\n* [pg-proto-parser](https://github.com/constructive-io/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.\n\n## Disclaimer\n\nAS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED \"AS IS\", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.\n\nNo developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructive-io%2Fpgpm-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructive-io%2Fpgpm-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructive-io%2Fpgpm-modules/lists"}