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/pgcentralfoundation/pgrx 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 2w ago
• 16 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 pgcentralfoundation/pgrx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pgcentralfoundation/pgrx.

What it runs against: a local clone of pgcentralfoundation/pgrx — 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 pgcentralfoundation/pgrx | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 46 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pgcentralfoundation/pgrx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pgcentralfoundation/pgrx.git
#   cd pgrx
#
# 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 pgcentralfoundation/pgrx and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "cargo-pgrx/src/main.rs" \\
  && ok "cargo-pgrx/src/main.rs" \\
  || miss "missing critical file: cargo-pgrx/src/main.rs"
test -f "pgrx/src/lib.rs" \\
  && ok "pgrx/src/lib.rs" \\
  || miss "missing critical file: pgrx/src/lib.rs"
test -f "pgrx-pg-sys/src/lib.rs" \\
  && ok "pgrx-pg-sys/src/lib.rs" \\
  || miss "missing critical file: pgrx-pg-sys/src/lib.rs"
test -f "pgrx-macros/src/lib.rs" \\
  && ok "pgrx-macros/src/lib.rs" \\
  || miss "missing critical file: pgrx-macros/src/lib.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 46 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~16d)"
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/pgcentralfoundation/pgrx"
  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).

pgrx is a Rust framework that lets developers build PostgreSQL extensions entirely in Rust, handling the unsafe FFI boundary with automatic safety guarantees. It provides idiomatic Rust bindings to Postgres internals, automatic SQL schema generation, and support for Postgres 13–18 from a single codebase. The core innovation is translating Rust panics into Postgres ERRORs without crashing the database process, and managing memory according to Rust's drop semantics even across FFI boundaries. Monorepo with 11 crates: pgrx (core extension APIs), cargo-pgrx (CLI tooling in cargo-pgrx/src/command/), pgrx-macros (procedural macros for #[pg_extern], #[pg_guard]), pgrx-pg-sys (raw Postgres FFI bindings), pgrx-sql-entity-graph (schema generation), and pgrx-examples/* (runnable reference extensions). cargo-pgrx is the developer entry point for cargo pgrx new/init/run/test/package commands.

Rust developers and database engineers building custom Postgres extensions who want type safety, memory safety, and rapid development without writing C. They're typically database administrators, systems engineers, or extension authors who want to leverage Rust's performance and ecosystem while avoiding C's memory management pitfalls.

Production-ready and actively maintained. The project is part of the PgCentral Foundation (as of 2023), has a published v0.18.0 release, comprehensive CI across multiple Postgres versions in .github/workflows/tests.yml, and supports an extensive test matrix. Regular updates and active Discord community indicate strong ongoing stewardship.

Low risk for core functionality, moderate risk for bleeding-edge features. The monorepo structure (11 interdependent crates in Cargo.toml workspace members) means changes ripple across packages, requiring careful coordination. Dependency on Postgres version-specific bindings (pgrx-pg-sys) means major Postgres releases may require updates. As a framework rather than library, extension developers inherit the pgrx maintenance burden.

The project has stabilized around Postgres 13–18 support, with ongoing work visible in workflow files (package-test.yaml, will-it-blend-develop.yml). The version is locked at 0.18.0 across workspace members, suggesting a release cycle. Recent additions include enhanced cross-compilation support (cargo-pgrx/src/command/cross/) and Docker build infrastructure for CI. No specific breaking changes are evident, but the 2024 edition marker in Cargo.toml suggests modernization is ongoing.

Clone the repo, install Rust and a Postgres installation (or let pgrx manage one), then use cargo-pgrx:

git clone https://github.com/pgcentralfoundation/pgrx.git
cd pgrx
cargo install --path cargo-pgrx
cargo pgrx init
cargo pgrx new my_extension
cd my_extension
cargo pgrx run pg15

This bootstraps a Postgres 15 environment and drops you into psql for interactive testing.

Daily commands: Development workflow via cargo-pgrx CLI:

cargo pgrx init              # Register Postgres installations
cargo pgrx run pg15          # Spin up Postgres 15 and open psql
cargo pgrx test              # Run unit tests across all Postgres versions
cargo pgrx package           # Build extension package (.tar.gz with .so/.control files)

Or for just the core library: cargo test -p pgrx to validate bindings and macros.

• Cargo.toml — Root workspace manifest defining all member crates and shared dependencies—essential for understanding the project structure and build system.
• cargo-pgrx/src/main.rs — Entry point for the cargo-pgrx CLI tool; every contributor must understand how commands are dispatched and which subcommands exist.
• pgrx/src/lib.rs — Core pgrx library façade exposing the main API surface for writing PostgreSQL extensions in Rust.
• pgrx-pg-sys/src/lib.rs — Low-level PostgreSQL bindings layer; critical for understanding how Rust FFI wraps C PostgreSQL internals.
• pgrx-macros/src/lib.rs — Procedural macros for declarative SQL generation and Rust-to-Postgres glue; every extension author relies on these.
• cargo-pgrx/src/command/mod.rs — Command module dispatcher routing cargo-pgrx subcommands; understanding this is essential for adding or modifying CLI workflows.
• README.md — Project overview, feature summary, and contribution guidance—first document to orient new developers.

Create a new PostgreSQL extension with pgrx

1. Run the scaffolding tool to generate a new extension skeleton (cargo-pgrx/src/command/new.rs)
2. Edit the generated lib.rs to define SQL functions with the #[pg_extern] macro (cargo-pgrx/src/templates/lib_rs)
3. Add Cargo.toml metadata and version constraints for target PostgreSQL versions (cargo-pgrx/src/templates/cargo_toml)
4. Run cargo pgrx init to download and prepare PostgreSQL dev environments (cargo-pgrx/src/command/init.rs)
5. Test the extension with cargo pgrx test against multiple PostgreSQL versions (cargo-pgrx/src/command/test.rs)
6. Generate the SQL schema with cargo pgrx schema (cargo-pgrx/src/command/schema.rs)
7. Package and distribute the extension using cargo pgrx package (cargo-pgrx/src/command/package.rs)

Define a PostgreSQL function exposed to SQL

1. Add a Rust function annotated with #[pg_extern] macro in your extension's lib.rs (pgrx-macros/src/lib.rs)
2. Use pgrx::prelude types (Datum, Text, Int32, etc.) for parameter and return types (pgrx/src/lib.rs)
3. The macro automatically generates SQL function signatures and handles FFI marshalling (pgrx-sql-entity-graph/src)
4. Generate SQL schema to see the created function signature (cargo-pgrx/src/command/schema.rs)

Handle PostgreSQL memory and error contexts safely

1. Use pgrx::PgMemoryContexts to allocate memory in PostgreSQL contexts (pgrx/src/lib.rs)
2. Wrap unsafe PostgreSQL C calls in Result types; pgrx macros auto-convert panic to PG errors (pgrx-macros/src/lib.rs)
3. Understand setjmp/longjmp behavior and PgTryBuilder for error recovery (docs/src/pg-internal/setjmp-longjmp.md)
4. Write tests using pgrx-tests to verify memory safety and error handling (pgrx-tests)

Add support for a new PostgreSQL version

1. Update the version matrix in the main Cargo.toml workspace definition (Cargo.toml)
2. Run pgrx-bindgen against the new PostgreSQL version's header files (pgrx-bindgen/src)
3. Merge generated FFI bindings into pgrx-pg-sys conditional compilation blocks (pgrx-pg-sys/src/lib.rs)
4. Add the version to the CI test matrix in .github/workflows/tests.yml (.github/workflows/tests.yml)

• Rust — Memory safety without garbage collection, zero-cost abstractions for FFI, and compile-time guarantees allow safe PostgreSQL extension development compared to C/C++.
• Procedural Macros (syn, quote) — Enable ergonomic #[pg_extern], #[pg_test] declarative syntax; automate boilerplate SQL generation and FFI marshalling code.
• PostgreSQL C API (FFI via bindgen) — Necessary to integrate with PostgreSQL internals (datums, memory contexts, error handling); bindgen automates version-specific binding generation.
• Multi-version support (Cargo features) — PostgreSQL 13–18 have API differences; conditional compilation via features and pgx-pg-config allows single codebase to target multiple versions.
• Docker & CI (GitHub Actions) — Isolate PostgreSQL build/test environments across platforms; automated testing against each supported PostgreSQL version.

• Unsafe FFI wrapper layer (pgrx-pg-sys) abstracted behind safe high-level API (pgrx)

  • Why: PostgreSQL C API is fundamentally unsafe; encapsulation provides safety checks at pgrx layer while allowing expert users access to low-level bindings if needed.
  • Consequence: Small runtime overhead from safety checks; requires careful auditing of unsafe blocks but prevents entire class of undefined behavior bugs.

• Macros generate SQL schema files automatically rather than writing schema manually

  • Why: Reduces duplication between Rust function signatures and SQL
  • Consequence: undefined

1. Postgres installation required: cargo pgrx init expects pg_config in PATH or will download/compile Postgres (~500 MB each version). Set PG_CONFIG env var to skip. 2. Panics are caught and converted to Postgres ERRORs only inside #[pg_guard] or #[pg_extern] functions; panics in thread code or async contexts will still crash. 3. The #[derive(PostgresType)] macro by default uses CBOR encoding; if you need a specific binary format, use #[pg_binary_protocol]. 4. Feature gating for Postgres versions is required in Cargo.toml for the extension crate itself; missing features cause link failures. 5. Memory allocated in Postgres must be freed in Postgres context (palloc/pfree); Rust Box will not work—use PgBox instead. 6. Schema generation happens at compile time; changes to #[pg_extern] signatures require cargo pgrx schema or cargo pgrx run to regenerate .sql files.

• Datum (PostgreSQL internal type) — Every value passed between Postgres and Rust is a Datum (word-sized opaque pointer or integer); understanding Datum encoding/decoding is fundamental to correct type marshalling in pgrx
• palloc/pfree (Postgres memory allocation) — Memory allocated in Postgres must use palloc, not malloc or Rust Box; pgrx's PgBox wrapper ensures Rust code respects this boundary and doesn't create dangling pointers across FFI
• pg_guard (exception safety macro) — Postgres uses longjmp for errors; #[pg_guard] ensures Rust destructors run even when Postgres calls elog(ERROR), preventing resource leaks and memory corruption
• SetOf/TableIterator (Postgres SETOF/TABLE returns) — Returning multiple rows from a function requires pgrx's iterator wrappers to correctly manage Postgres's SRF (Set-Returning Function) protocol and memory contexts
• Custom type serialization (CBOR vs. binary protocol) — Rust structs deriving PostgresType choose between CBOR (flexible, debuggable) or custom binary format (#[pg_binary_protocol]); this affects on-disk storage, network transmission, and performance
• Feature-gated Postgres version APIs — pgrx supports Postgres 13–18 from one codebase via Cargo features; functions/types only available in certain versions must be gated with #[cfg(feature = "pg15")], requiring careful version-aware code
• SQL entity graph (schema codegen) — pgrx-sql-entity-graph walks your Rust code's attributes at compile time to generate .sql files (CREATE FUNCTION, CREATE TYPE, etc.); understanding this AST is key to custom type registration and reproducible deployments

• postgres/postgres — Source of Postgres C headers and runtime; pgrx-pg-sys generates bindings against this
• zombodb/zombodb — Full-text search Postgres extension written in early pgrx; historical predecessor and reference implementation
• tembo-io/tembo — Postgres extension platform/marketplace built on pgrx; shows production use of pgrx for shipping extensions
• tcdi/pgx — Earlier Rust FFI bindings for Postgres (pre-pgrx era); influenced pgrx design but pgrx is now the standard
• neondatabase/neon — Serverless Postgres platform that uses pgrx extensions in its ecosystem; represents deployment target for pgrx extensions

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 integration tests for cargo-pgrx command lifecycle

The cargo-pgrx subcommands (init, new, install, start, stop, test, bench, etc.) in cargo-pgrx/src/command/ lack integration tests that verify the full workflow. Currently there are no tests validating that cargo pgrx new, cargo pgrx init, and cargo pgrx install work end-to-end with real Postgres installations. This is critical since cargo-pgrx is the primary CLI tool users interact with.

• [ ] Create cargo-pgrx/tests/integration/ directory structure
• [ ] Add integration test file for init/new commands that validates project structure creation
• [ ] Add integration test for install/start/stop commands with Docker containers (see .github/docker/ Dockerfiles)
• [ ] Reference existing test patterns in pgrx-tests/ and pgrx-unit-tests/ workspace members

Add missing GitHub Actions workflow for cross-compilation testing

The repo contains cargo-pgrx/src/command/cross/pgrx_target.rs for cross-compilation support, but .github/workflows/ lacks a dedicated CI workflow to test cross-compilation targets (e.g., aarch64, x86_64 on non-native platforms). Current .github/workflows/tests.yml doesn't validate the cross-compilation code paths, leaving this critical feature untested in CI.

• [ ] Create .github/workflows/cross-compile-test.yaml workflow file
• [ ] Add job matrix for testing cross-compilation targets using cargo-pgrx cross command
• [ ] Integrate with existing Docker images in .github/docker/ for testing environments
• [ ] Validate that pgrx_target.rs logic is exercised for at least 2-3 target platforms

Add comprehensive CLI help text and example documentation for cargo-pgrx commands

cargo-pgrx/src/command/ contains many subcommands (bench.rs, connect.rs, regress.rs, schema.rs, etc.) but articles/README.md and main README.md lack specific examples and documentation for each command. Users must infer behavior from code. Adding command-specific documentation with real-world examples would significantly improve discoverability.

• [ ] Create articles/cargo-pgrx-commands-guide.md documenting each command in cargo-pgrx/src/command/
• [ ] Include practical examples for: cargo pgrx bench, cargo pgrx connect, cargo pgrx regress, cargo pgrx schema
• [ ] Add troubleshooting section with common errors from command/*.rs error handling
• [ ] Link new guide from main README.md and ensure consistency with clap command definitions in command/mod.rs

• Add integration tests for pgrx-bindgen/ that verify FFI bindings remain accurate when upgrading Postgres minor versions; currently build.rs auto-generates but there's no regression suite to catch subtle API drift.
• Document the memory model for custom Postgres types: add examples in pgrx-examples/ showing PgBox allocation, CBOR vs. binary protocol trade-offs, and dangling pointer scenarios (currently only in generated docs, not tutorials).
• Extend cargo-pgrx/src/command/info.rs to print detected Postgres versions, pg_config paths, and feature flags to .cargo/config.toml; new users often get silent failures when pgrx can't find Postgres installs.

The pgrx project demonstrates reasonable security awareness with a defined SECURITY.md policy and proper repository structure for handling security issues. However, there are configuration issues with the Cargo.toml (invalid Rust edition and incomplete dependencies) that need immediate attention. The incomplete SECURITY.md file should be completed. Docker and GitHub Actions configurations require additional review to ensure no supply chain vulnerabilities or secrets exposure. Overall security posture is moderate with room for improvement in documentation completeness and configuration validation.

• Medium · Incomplete SECURITY.md File — SECURITY.md. The SECURITY.md file appears to be truncated and incomplete. The security policy documentation cuts off mid-sentence at 'Thi', which may indicate incomplete security guidelines or missing critical security information for vulnerability disclosure. Fix: Complete and finalize the SECURITY.md file with comprehensive security policies, vulnerability disclosure procedures, and security contact information.
• Low · Deprecated Rust Edition in Workspace Configuration — Cargo.toml (workspace.package). The Cargo.toml specifies edition = '2024', which does not exist as a valid Rust edition. Valid editions are 2015, 2018, and 2021. This may cause build failures or unexpected behavior across all workspace members. Fix: Update the edition field to a valid Rust edition, preferably '2021' for latest features and safety improvements.
• Low · Incomplete Dependency Lock Information — Cargo.toml (workspace.dependencies section). The workspace dependencies section in Cargo.toml appears truncated (ends with 'quo' without completion). This incomplete configuration could lead to unpredictable dependency resolution and potential mismatches between actual and intended dependencies. Fix: Complete the dependency declarations and ensure all dependencies are fully specified with proper versions and features.
• Low · Docker Configuration Files Present — .github/docker/. Multiple Dockerfile configurations exist (.github/docker/Dockerfile.*) without visible review in the security analysis. Docker configurations can introduce supply chain risks if base images are not regularly updated or if inappropriate permissions are granted. Fix: Regularly scan and audit Dockerfile configurations for security best practices: use specific image versions (not 'latest'), run with minimal privileges, minimize attack surface, and use multi-stage builds.
• Low · GitHub Actions Workflow Security — .github/workflows/. Multiple GitHub Actions workflow files are present (.github/workflows/*.yml) which could potentially contain insecure practices such as hardcoded secrets, overly permissive permissions, or use of untrusted third-party actions. Fix: Audit all workflow files for: (1) use of secrets management via GitHub Secrets, not hardcoded credentials, (2) minimal GITHUB_TOKEN permissions, (3) trusted and version-pinned third-party actions, (4) no sensitive data in logs.

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.