{"id":50493062,"url":"https://github.com/get-felipe/pg-contract","last_synced_at":"2026-06-02T05:00:26.900Z","repository":{"id":361919283,"uuid":"1256411399","full_name":"get-felipe/pg-contract","owner":"get-felipe","description":"Postgres query compatibility checks for schema changes.","archived":false,"fork":false,"pushed_at":"2026-06-01T21:09:37.000Z","size":68,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T21:22:53.834Z","etag":null,"topics":["database","github-actions","go","postgres","postgresql","sql"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/get-felipe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2026-06-01T18:51:35.000Z","updated_at":"2026-06-01T21:05:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/get-felipe/pg-contract","commit_stats":null,"previous_names":["get-felipe/pg-contract"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/get-felipe/pg-contract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/get-felipe%2Fpg-contract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/get-felipe%2Fpg-contract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/get-felipe%2Fpg-contract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/get-felipe%2Fpg-contract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/get-felipe","download_url":"https://codeload.github.com/get-felipe/pg-contract/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/get-felipe%2Fpg-contract/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33806987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["database","github-actions","go","postgres","postgresql","sql"],"created_at":"2026-06-02T05:00:18.907Z","updated_at":"2026-06-02T05:00:26.888Z","avatar_url":"https://github.com/get-felipe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pg-contract\n\nPostgres query compatibility checks for schema changes.\n\n`pg-contract` answers one narrow question:\n\n\u003e Do the application SQL queries that work against the current Postgres schema still prepare successfully against the proposed schema?\n\nIt is not a schema diff tool, migration runner, ORM, or hosted service. It validates real SQL against real Postgres schemas and reports the exact query, source file, SQLSTATE, and diagnostic reason when a schema change breaks an existing query.\n\n## Status\n\nPre-release alpha. The core `check` command works for `.sql` query files, user-provided Postgres URLs, optional schema SQL files, query manifest v0.2, JSON output, and GitHub Actions annotations.\n\nThe project is useful for early adopters, but command flags and report fields may still change before a stable release.\n\n## Why pg-contract?\n\nSchema diff tools can tell you what changed in the database. Migration linters can warn about lock hazards and unsafe operations. Those are useful, but they do not answer whether your existing application queries still compile against the new schema.\n\n`pg-contract` is designed for that missing contract:\n\n- Prepare the same SQL against a before schema and an after schema.\n- Treat valid-before/fail-after as a breaking application contract change.\n- Use Postgres itself as the source of truth for query validity.\n- Keep diagnostics close to the query file that needs attention.\n- Fit into local development and pull-request checks without owning your migration workflow.\n\n## Install\n\nFrom a tagged release:\n\n```sh\ngo install github.com/get-felipe/pg-contract/cmd/pg-contract@v0.1.0-alpha.5\n```\n\nFrom source:\n\n```sh\ngit clone https://github.com/get-felipe/pg-contract.git\ncd pg-contract\nmake build\n./bin/pg-contract version\n```\n\nGitHub Release archives are produced for Linux, macOS, and Windows on `amd64` and `arm64`. Each release includes a SHA-256 checksum file.\n\nSee [Installation](docs/INSTALLATION.md) for release archive downloads, checksum verification, and platform-specific commands.\n\n## Quick Start\n\nCreate two disposable Postgres databases: one for the current schema and one for the proposed schema.\n\n```sh\ncreatedb pg_contract_before\ncreatedb pg_contract_after\n```\n\nRun a compatibility check:\n\n```sh\npg-contract check \\\n  --before-url \"$PG_CONTRACT_BEFORE_URL\" \\\n  --after-url \"$PG_CONTRACT_AFTER_URL\" \\\n  --schema-before examples/basic/schema-before.sql \\\n  --schema-after examples/basic/schema-after.sql \\\n  --queries examples/basic/queries\n```\n\nExample output:\n\n```text\nFAIL customers.find_customer\nFile: examples/basic/queries/find_customer.sql:2\n\nReason:\n  A column referenced by this query does not exist in the target schema.\n\nPostgres error:\n  ERROR: column \"email\" does not exist\n  SQLSTATE: 42703\n\nImpact:\n  This query worked before the schema change and fails after it.\n\nSuggested fix:\n  Keep the old column until deployed application code no longer reads it, or update this query before removing the column.\n```\n\nExit codes:\n\n- `0`: no valid-before/fail-after breakages were found.\n- `1`: at least one existing query breaks against the after schema.\n- `2`: input, runtime, or invalid-before error.\n\n## Query Files\n\n`pg-contract` scans `.sql` files recursively. Use sqlc-style names when possible:\n\n```sql\n-- name: customers.find_customer :one\nselect id, email\nfrom customers\nwhere id = $1;\n```\n\nIf no `-- name:` comment exists, the file path is used as the query name.\n\n## Configuration\n\nSome SQL parameters cannot be inferred by Postgres during `PREPARE`. Generate a starter config when a query needs explicit parameter types:\n\n```sh\npg-contract init --queries ./queries --out pg-contract.yaml\n```\n\n```yaml\nqueries:\n  search.count_tags:\n    params:\n      - text[]\n```\n\n`check` automatically loads `pg-contract.yaml` from the current directory when it exists. Use `--config path/to/file.yaml` for an explicit path, or `--no-config` to disable config loading.\n\nFor larger repositories, use manifest v0.2 to put query roots and schema files in config:\n\n```yaml\nversion: \"0.2\"\n\nquery_sets:\n  - name: app\n    queries:\n      - ./queries\n    schema:\n      before:\n        - ./schema-before.sql\n      after:\n        - ./schema-after.sql\n```\n\n```sh\npg-contract check \\\n  --before-url \"$PG_CONTRACT_BEFORE_URL\" \\\n  --after-url \"$PG_CONTRACT_AFTER_URL\" \\\n  --config pg-contract.yaml\n```\n\nRun one or more manifest query sets when a PR only touches part of a larger repository:\n\n```sh\npg-contract check \\\n  --before-url \"$PG_CONTRACT_BEFORE_URL\" \\\n  --after-url \"$PG_CONTRACT_AFTER_URL\" \\\n  --config pg-contract.yaml \\\n  --query-set app\n```\n\nSee [Configuration](docs/CONFIGURATION.md) for details.\n\n## Output Formats\n\nText output is intended for humans:\n\n```sh\npg-contract check \\\n  --before-url \"$PG_CONTRACT_BEFORE_URL\" \\\n  --after-url \"$PG_CONTRACT_AFTER_URL\" \\\n  --queries ./queries\n```\n\nJSON output is intended for tools:\n\n```sh\npg-contract check \\\n  --before-url \"$PG_CONTRACT_BEFORE_URL\" \\\n  --after-url \"$PG_CONTRACT_AFTER_URL\" \\\n  --queries ./queries \\\n  --format json\n```\n\nJSON reports include status, summary counts, query source locations, SQLSTATE, and diagnostic fields. They do not include database URLs or raw query text.\n\nSee [Diagnostics](docs/DIAGNOSTICS.md) for the SQLSTATE mappings behind text, JSON, and GitHub annotation output.\n\n## GitHub Actions\n\n```yaml\n- uses: get-felipe/pg-contract@v0.1.0-alpha.5\n  with:\n    before-url: ${{ secrets.PG_CONTRACT_BEFORE_URL }}\n    after-url: ${{ secrets.PG_CONTRACT_AFTER_URL }}\n    queries: ./queries\n```\n\nThe action emits GitHub workflow command annotations with file and line metadata. Use a pinned release tag or commit SHA in production workflows.\n\nSee [GitHub Actions](docs/GITHUB_ACTIONS.md) for a complete workflow.\n\n## Known Limitations\n\n- Only Postgres is supported.\n- Queries must be available as `.sql` files; SQL extraction from application code is not implemented.\n- Dynamic SQL and runtime string interpolation are not analyzed.\n- Queries are prepared, not executed; data-dependent runtime failures are out of scope.\n- The tool does not create production-safe migrations or analyze lock impact.\n- The user provides the before and after Postgres databases.\n- Pre-release output fields and flags may change.\n\n## Roadmap\n\nNear-term:\n\n- Prepare the next alpha release with broader fixture coverage.\n- Improve diagnostics for more Postgres SQLSTATEs.\n- Add PR-focused documentation for common CI setups.\n- Add focused fixtures for result-shape limitations and additional SQLSTATEs.\n- Add tag filtering for manifest workflows.\n\nLater:\n\n- Optional query extraction adapters.\n- Richer GitHub PR summaries.\n- Package manager distribution once the release shape is stable.\n\n## Development\n\nRequirements:\n\n- Go 1.26 or newer.\n- Git.\n- Two Postgres databases for integration checks.\n\nCommon commands:\n\n```sh\nmake test\nmake build\nmake check\nmake test-integration\nmake release-check\n```\n\nRun examples locally:\n\n```sh\ncp .env.example .env.local\nmake example-basic\nmake example-missing-table\nmake example-ambiguous-column\nmake example-view-changed\nmake example-function-signature\nmake example-enum-value\nmake example-search-path\nmake example-typed-params\nmake example-manifest-v02\nmake example-basic FORMAT=json\n```\n\nUse disposable databases when passing `--schema-before` or `--schema-after`; those files are executed against the supplied URLs.\n\n## Project Boundaries\n\nIn scope:\n\n- Postgres query compatibility checks.\n- Local CLI and GitHub Action workflows.\n- SQL files and explicit query metadata.\n- Clear diagnostics for valid-before/fail-after breakages.\n\nOut of scope:\n\n- Migration generation.\n- Migration execution in production.\n- Lock/downtime planning.\n- ORM-specific behavior.\n- Hosted dashboards or cloud-required workflows.\n\n## Documentation\n\n- [Project brief](docs/PROJECT_BRIEF.md)\n- [Installation](docs/INSTALLATION.md)\n- [Changelog](CHANGELOG.md)\n- [Plan](docs/PLAN.md)\n- [Environment](docs/ENVIRONMENT.md)\n- [Configuration](docs/CONFIGURATION.md)\n- [Diagnostics](docs/DIAGNOSTICS.md)\n- [Query manifest v0.2](docs/QUERY_MANIFEST_V02.md)\n- [GitHub Actions](docs/GITHUB_ACTIONS.md)\n- [Releasing](docs/RELEASING.md)\n- [Reference analysis](docs/REFERENCE_ANALYSIS.md)\n\n## Contributing\n\nContributions are welcome, especially small fixtures, diagnostic improvements, documentation fixes, and focused bug reports. Read [Contributing](CONTRIBUTING.md) before opening a pull request.\n\n## Security\n\nPlease do not open public issues with sensitive database URLs, credentials, schema details, or vulnerability proof-of-concepts. Read [Security Policy](SECURITY.md) for reporting guidance.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fget-felipe%2Fpg-contract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fget-felipe%2Fpg-contract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fget-felipe%2Fpg-contract/lists"}