If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/supabase/pg_graphql shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 9 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live supabase/pg_graphql repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/supabase/pg_graphql.

What it runs against: a local clone of supabase/pg_graphql — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in supabase/pg_graphql | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of supabase/pg_graphql. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/supabase/pg_graphql.git
#   cd pg_graphql
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of supabase/pg_graphql and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "supabase/pg_graphql(\\.git)?\\b" \\
  && ok "origin remote is supabase/pg_graphql" \\
  || miss "origin remote is not supabase/pg_graphql (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/graphql.rs" \\
  && ok "src/graphql.rs" \\
  || miss "missing critical file: src/graphql.rs"
test -f "src/transpile.rs" \\
  && ok "src/transpile.rs" \\
  || miss "missing critical file: src/transpile.rs"
test -f "src/resolve.rs" \\
  && ok "src/resolve.rs" \\
  || miss "missing critical file: src/resolve.rs"
test -f "src/builder.rs" \\
  && ok "src/builder.rs" \\
  || miss "missing critical file: src/builder.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/supabase/pg_graphql"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

pg_graphql is a PostgreSQL extension (written in Rust using pgrx) that automatically generates a GraphQL API from your existing SQL schema. It reflects tables, foreign keys, and custom types directly into GraphQL types and queries, enabling serverless GraphQL queries without a separate API layer—all executed inside PostgreSQL itself. Single-crate Rust library exposing C-compatible functions via pgrx. Core logic in src/ (inferred), with bin/pgrx_embed_pg_graphql as the embedding binary. Tests are integration-based via pgrx-tests (SQL-side via dockerfiles/db/setup.sql). Documentation and examples live in docs/ and dockerfiles/ directories. Feature gates allow compilation against PostgreSQL 14–18.

Backend engineers and database architects using Supabase or self-hosted PostgreSQL who want to expose their relational database via GraphQL without building and maintaining separate API servers. Also attractive to teams building serverless applications where co-locating data logic with the database reduces operational complexity.

Production-ready. The project is actively maintained (version 1.6.1), supports PostgreSQL 14–18 with dedicated feature flags, has comprehensive CI/CD via GitHub Actions (test.yml, coverage.yml, release.yml), and includes extensive documentation in docs/. The codebase is substantial (473KB Rust) and used by Supabase, a well-known platform.

Low risk overall, but worth noting: single organization (Supabase) stewardship, limited public contributor visibility in file list, and tight coupling to PostgreSQL internals via pgrx (version pinned to =0.16.1) means breaking changes upstream could require version bumps. Dependency footprint is reasonable (~15 top-level deps) with stable crates (serde, graphql-parser). No recent security advisories visible in common package info.

Actively maintained with support for PostgreSQL 18 (default feature). The changelog (docs/changelog.md) and recent docs (docs/configuration.md, docs/functions.md) indicate ongoing feature refinement. CI is comprehensive with coverage tracking, suggesting active development cycles.

git clone https://github.com/supabase/pg_graphql.git
cd pg_graphql
cargo build --release --features pg18
# For testing:
docker-compose up -d
cargo test --features pg_test,pg18

See Cargo.toml (edition 2024, MSRV likely Rust 1.70+) and docs/installation.md for environment setup.

Daily commands: Development: cargo build --features pg18. Testing: docker-compose up && cargo test --features pg_test,pg18. The project uses pgrx's managed PostgreSQL test instance; see .github/workflows/test.yml for CI patterns. No separate dev server—the extension runs inside PostgreSQL itself, queries via HTTP endpoint defined by deployment (e.g., Supabase).

• src/lib.rs — Entry point for the PGRX extension; exports all public GraphQL functions and initializes the PostgreSQL extension module.
• src/graphql.rs — Core GraphQL schema introspection and query validation logic; handles conversion of SQL schema to GraphQL types.
• src/transpile.rs — Translates GraphQL queries into executable SQL; critical path for query execution performance.
• src/resolve.rs — Query resolution engine that executes transpiled SQL and formats results; handles field resolution and pagination.
• src/builder.rs — Constructs GraphQL schema from PostgreSQL catalog metadata; bridges SQL introspection and GraphQL type system.
• Cargo.toml — Defines PGRX version and PostgreSQL compatibility features (pg14–pg18); critical for build configuration.
• sql/resolve.sql — SQL interface definition for the main GraphQL resolution function exposed to PostgreSQL.

Add support for a new PostgreSQL type mapping

1. Define the new type mapping in src/sql_types.rs, adding a variant to the type resolver (src/sql_types.rs)
2. Update src/builder.rs to handle the new type when constructing GraphQL field types (src/builder.rs)
3. Add test case in test/expected with SQL schema using the new type (test/expected/new_type_mapping.out)

Add a new GraphQL directive or configuration option

1. Define the directive in src/constants.rs with naming conventions (src/constants.rs)
2. Implement directive parsing and validation in src/parser_util.rs (src/parser_util.rs)
3. Add handling in src/builder.rs or src/graphql.rs to apply directive logic during schema building (src/builder.rs)
4. Document the directive in docs/configuration.md or docs/api.md (docs/configuration.md)

Optimize query performance with a new transpilation rule

1. Identify the query pattern to optimize and analyze in src/transpile.rs (src/transpile.rs)
2. Implement the SQL generation optimization in src/transpile.rs (src/transpile.rs)
3. Add or update caching strategy if needed in src/lib.rs using the cached crate (src/lib.rs)
4. Add benchmark/test case in test/expected (test/expected/performance_case.out)

Support a new PostgreSQL feature (e.g., generated columns, new function type)

1. Add type/feature detection in src/builder.rs during schema introspection (src/builder.rs)
2. Update src/transpile.rs to handle the new feature in query compilation (src/transpile.rs)
3. Add documentation in docs/example_schema.md or docs/functions.md (docs/example_schema.md)
4. Add integration test in test/expected (test/expected/new_feature.out)

• PGRX (PostgreSQL Rust bindings) — Enables safe, type-safe Rust extensions for PostgreSQL; avoids C complexity while providing direct pg_catalog access.
• graphql-parser crate — Provides robust GraphQL query parsing; delegates syntax validation to a maintained third-party library.
• serde + serde_json — Efficient serialization of complex nested GraphQL responses and schema introspection data.
• cached crate — Memoizes schema introspection results across requests to avoid repeated pg_catalog queries.
• Rust + compilation to shared object — Memory-safe, performant native code execution within PostgreSQL process; no network round-trips.

• Schema introspection at query time (with caching) rather than pre-computed static schema

  • Why: Allows dynamic schema changes without extension restart; supports stored procedures and views that may be modified.
  • Consequence: First query in a cache window incurs introspection overhead; requires cache invalidation strategy.

• GraphQL query → SQL transpilation instead of interpretation/execution in Rust

  • Why: Leverages PostgreSQL query planner and optimizer; results are directly executable without overhead.
  • Consequence: Complex filter/aggregation logic must be correctly translated to SQL; harder to debug than single-language execution.

• Reflection-based schema from SQL catalog rather than decorators/annotations

  • Why: Zero configuration; works with existing schemas; schema always matches actual database state.
  • Consequence: Less control over GraphQL naming/structure; requires directives for customization; migration from other GraphQL backends is harder.

• Single Rust process extension rather than separate microservice

  • Why: Lower latency, no network overhead, simpler deployment, single source of truth in database.
  • Consequence: Rust bug can crash PostgreSQL server; complex features harder to isolate; limited horizontal scaling.

• Does not handle authentication or authorization (delegates to PostgreSQL RLS and database-level permissions).
• Does not provide real-time subscriptions or live queries (no WebSocket support).
• Does not support mutations on arbitrary SQL (mutations are limited to INSERT/UPDATE/DELETE on tables via GraphQL).
• Not designed for extreme query complexity; cannot transpile all SQL features into GraphQL.
• No built-in caching beyond schema introspection; response caching delegated to application/proxy layer.
• Does not support custom scalar serialization beyond PostgreSQL native types.

PostgreSQL version lock: Features are gated by pg14–pg18; using wrong feature flag causes build failures. pgrx version parity: pgrx is pinned to =0.16.1; Cargo.lock enforces exact match, so cargo update is restricted and must be coordinated with pgrx releases. SQL schema assumptions: The extension relies on reading pg_catalog and table/type metadata; if running in restricted PostgreSQL environments, introspection may fail silently. No schema reload after DDL: Cached schema (via cached crate) requires restart/cache invalidation after ALTER TABLE; see docs/configuration.md for cache control. PLpgSQL test data: Tests assume specific schemas in setup.sql; incomplete setups cause cryptic test failures.

• PostgreSQL Extension API (C FFI via pgrx) — pg_graphql runs as a native PostgreSQL extension, not a standalone server; understanding how pgrx bridges Rust to PostgreSQL's C API is critical for debugging and contributing.
• Schema Introspection & Reflection — The core feature: automatically discovering tables, columns, types, and relationships from pg_catalog without manual schema definition; central to how pg_graphql generates GraphQL types.
• GraphQL Type System & Schema Stitching — pg_graphql translates SQL entities to GraphQL types, enums, and relationships; understanding GraphQL type composition is needed to predict schema generation behavior.
• Inflection (Name Case Transformation) — The extension supports automatic snake_case → camelCase/PascalCase inflection via config; this is a key feature enabling idiomatic GraphQL naming without explicit SQL aliasing.
• Foreign Key Relationship Resolution — GraphQL relationships in pg_graphql are derived from PostgreSQL foreign keys; understanding how the extension maps 1:N, N:M, and self-referential FKs to connection types is essential.
• Query Planning & SQL Code Generation — GraphQL queries are compiled to SQL inside PostgreSQL; understanding filter/sort/pagination code generation helps debug query performance and mutation behavior.
• Bidirectional Type Mapping (bimap) — The bimap crate maintains reversible mappings between SQL names and GraphQL names (e.g., blog_post ↔ BlogPost); essential for supporting inflection and round-trip compatibility.

• PostgREST/postgrest — REST API layer for PostgreSQL with automatic schema introspection; complementary approach to pg_graphql's GraphQL-native alternative.
• graphql-engine/graphql-engine — Hasura's standalone GraphQL engine for PostgreSQL; similar goal but runs as external service vs. pg_graphql's in-database extension model.
• supabase/supabase — Parent project and primary consumer of pg_graphql; Supabase uses it as the default GraphQL interface for hosted PostgreSQL.
• tcdi/pgrx — The foundational Rust-PostgreSQL FFI framework (v0.16.1) that pg_graphql is built on; understanding pgrx macros and extension patterns is essential.
• graphql-rust/juniper — Alternative Rust GraphQL library for building schemas programmatically; contextually useful for understanding GraphQL fundamentals in Rust.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for src/builder.rs with unit tests

src/builder.rs is a core module (appears to handle GraphQL schema building) but there's no dedicated test file. The test.yml workflow runs pg_test features, but unit tests for the builder logic would catch regressions earlier and document expected behavior. This is critical for a schema reflection system where builder correctness directly impacts query functionality.

• [ ] Create tests/builder_tests.rs or add #[cfg(test)] module to src/builder.rs
• [ ] Add tests for schema type inference logic (tables, views, computed fields)
• [ ] Add tests for directive parsing from SQL comments
• [ ] Add tests for type coercion and field mapping edge cases
• [ ] Integrate into coverage.yml workflow to track builder test coverage

Add PostgreSQL version compatibility matrix to CI/docs

The repo supports pg14-pg18 (via features in Cargo.toml) but .github/workflows/test.yml likely runs against only one version. The README shows '14+' support but there's no visible CI matrix testing all supported versions. This prevents catching version-specific bugs before release.

• [ ] Update .github/workflows/test.yml to use matrix strategy testing pg14, pg15, pg16, pg17, pg18 features
• [ ] Update .github/workflows/coverage.yml to test against minimum supported version (pg14)
• [ ] Add a TESTING.md doc in docs/ listing tested PostgreSQL versions and known version-specific limitations
• [ ] Add version compatibility badges to README.md

Document SQL interface internals in docs/sql_interface.md with function signatures

docs/sql_interface.md exists but sql/resolve.sql, sql/directives.sql, and sql/load_sql_context.sql appear to expose functions without documented signatures or examples. Contributors and users need to understand which SQL functions to call, their parameters, and return types for custom integrations.

• [ ] Reverse-engineer and document all public SQL functions from sql/*.sql files (e.g. graphql(), graphql_explain())
• [ ] Add function signatures with parameter types and return types
• [ ] Add example SQL calls showing typical usage patterns
• [ ] Document the SQL config/context system (what load_sql_config.sql and load_sql_context.sql do)
• [ ] Link to source files in sql/ directory for reference

• Add documentation examples for computed_fields.md covering full CRUD workflows with PostgreSQL generated columns or function-backed fields (see docs/computed_fields.md exists but may lack SQL examples).
• Extend tests in dockerfiles/db/setup.sql to cover edge cases in type coercion: test UUID primary keys, JSONB columns, and enum types in mutations; currently PLpgSQL test coverage appears basic.
• Create a docs/troubleshooting.md with common errors (cache invalidation, schema not reflecting, inflection gotchas) cross-referencing docs/configuration.md and docs/sql_interface.md.

• High · Hardcoded Database Credentials in Docker Compose — docker-compose.yaml. The docker-compose.yaml file contains hardcoded database credentials (POSTGRES_USER: postgres, POSTGRES_PASSWORD: password) and exposes the database service on port 5406. These credentials are plaintext and easily discoverable in version control. Fix: Use environment variables or Docker secrets. Replace hardcoded values with ${POSTGRES_USER}, ${POSTGRES_PASSWORD} and load from .env file (add .env to .gitignore). Use Docker secrets for production deployments.
• High · Insecure PostgREST Configuration — docker-compose.yaml (rest service). The PostgREST service is configured with plaintext database URI containing credentials (postgres://postgres:password@db:5432/graphqldb) and uses default anonymous role without authentication enforcement visible in the configuration. Fix: Extract credentials to environment variables, implement JWT authentication, restrict the anon role permissions, and use HTTPS in production. Set PGRST_JWT_SECRET and configure proper role-based access control.
• Medium · Outdated Rust Edition in Cargo.toml — Cargo.toml. The Cargo.toml specifies edition = '2024' which does not exist as of current Rust standards. Valid editions are 2015, 2018, and 2021. This is likely a typo and should be corrected. Fix: Change edition to a valid value, preferably 2021: 'edition = "2021"'
• Medium · Dependency Pinning Without Lock File Review — Cargo.toml and Cargo.lock. Multiple dependencies are pinned to specific versions (e.g., pgrx = '=0.16.1', cached = '0.46.0'). While pinning is good practice, the Cargo.lock file should be reviewed for transitive dependencies and checked for known vulnerabilities. Fix: Run 'cargo audit' to scan for known vulnerabilities in dependencies. Implement automated dependency scanning in CI/CD pipeline (appears present but verify it includes cargo audit).
• Medium · Exposed Database Port in Development Configuration — docker-compose.yaml (db service ports). The PostgreSQL database is exposed on port 5406 with a publicly accessible container configuration. This could allow unauthorized access if the docker-compose is deployed in a shared environment. Fix: Bind the database port to localhost only: 'ports: ["127.0.0.1:5406:5432"]' for development. In production, do not expose the database port externally; use a network layer or VPC.
• Medium · GraphQL Parser Dependency Version — Cargo.toml (graphql-parser = '0.4'). The graphql-parser dependency is pinned to version 0.4, which may have security issues or missing features. Version is relatively old and should be audited. Fix: Check for security advisories for graphql-parser 0.4. Consider upgrading to the latest version and validate compatibility with the codebase. Run 'cargo audit' to identify any known CVEs.
• Low · Missing Security Headers Documentation — docker-compose.yaml, docs/security.md. While the project includes security documentation (docs/security.md), the docker-compose configuration does not explicitly show security headers being set for the GraphiQL interface or PostgREST service. Fix: Add security headers (X-Content-Type-Options, X-Frame-Options, Content-Security-Policy) to the GraphiQL and PostgREST service configurations. Document CORS policies and authentication requirements.
• Low · Incomplete Docker Compose File — docker-compose.yaml (graphiql service). The docker-compose.yaml file appears truncated ('container_na' without completion for graphiql service), which may indicate incomplete or improperly formatted configuration. Fix: Complete the graphiql service configuration. Ensure the file is valid and properly formatted. Add security-relevant configurations like restart policies and health checks.
• Low · Test Database Uses Weak Credentials — undefined. The setup.sql loaded in docker-entrypoint-initdb.d may contain Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.