Contributing to pg_trickle

Thank you for your interest in contributing! pg_trickle is an Apache 2.0-licensed open-source project and welcomes contributions of all kinds.

Before You Start

• Check the open issues and discussions to avoid duplicating work.
• For non-trivial changes, open an issue first to discuss the approach.
• Read AGENTS.md — it is the authoritative guide for all coding conventions, error handling rules, module layout, and test requirements.
• Read docs/ARCHITECTURE.md to understand the system.
• Read ROADMAP.md to see what work is planned.

Ways to Contribute

Development Setup

# Install pgrx
cargo install cargo-pgrx --version "=0.17.0"
cargo pgrx init --pg18 /usr/lib/postgresql/18/bin/pg_config

# Build
cargo build

# Format + lint (required before every PR)
just fmt
just lint

# Run tests
just test-unit          # fast, no DB
just test-integration   # Testcontainers
just test-e2e           # full E2E (builds Docker image)

Full setup instructions are in INSTALL.md.

Devcontainer / Containerized Development

If you are developing in a devcontainer, use the default non-root vscode user and run the normal commands from the workspace root:

just fmt
just lint
just test-unit

just test-unit uses scripts/run_unit_tests.sh, which now selects a writable and cache-friendly target directory in this order:

1. target/ (preferred)
2. .cargo-target/ (project-local fallback)
3. $HOME/.cache/pg_trickle-target
4. ${TMPDIR:-/tmp}/pg_trickle-target (last resort)

This avoids permission failures on bind mounts and preserves incremental builds when source or test files change.

If you see permission errors in containerized runs, verify you are not forcing a different container user/UID than expected by your workspace mount.

Run E2E tests in devcontainer

E2E tests use Testcontainers and require Docker access from inside the devcontainer (provided by the Docker-in-Docker feature in .devcontainer/devcontainer.json).

Run from the workspace root inside the devcontainer:

just build-e2e-image
just test-e2e

Notes:

• The E2E harness starts containers via testcontainers (tests/e2e/mod.rs).
• The default E2E image is pg_trickle_e2e:latest (built by tests/build_e2e_image.sh).
• A plain docker run of the dev image is not equivalent to a full VS Code devcontainer session with features/lifecycle hooks enabled.

Making a Pull Request

1. Fork the repository and create a branch: git checkout -b fix/my-fix
2. Make your changes following the conventions in AGENTS.md
3. Run just fmt && just lint — both must pass with zero warnings
4. Add or update tests — see AGENTS.md § Testing
5. Open a PR against main

The PR template will walk you through the checklist.

CI Coverage on PRs

PR CI runs unit tests (Linux only) and integration tests. E2E tests, TPC-H tests, benchmarks, dbt, and CNPG smoke tests are skipped on PRs to keep the feedback loop fast (~15 min).

To trigger the full CI matrix on your PR branch (recommended for DVM engine, refresh, or CDC changes):

gh workflow run ci.yml --ref <your-branch>

To run all tests locally before pushing:

just test-all          # unit + integration + e2e

# TPC-H correctness tests (requires e2e Docker image):
cargo test --test e2e_tpch_tests -- --ignored --test-threads=1 --nocapture

See AGENTS.md § Testing for the full CI coverage matrix.

Coding Conventions (summary)

• No unwrap() or panic!() in non-test code
• All unsafe blocks require a // SAFETY: comment
• Errors go through PgTrickleError in src/error.rs
• New SQL functions use #[pg_extern(schema = "pgtrickle")]
• Tests use Testcontainers — never a local PostgreSQL instance

Full details are in AGENTS.md.

Commit Messages

Use Conventional Commits:

fix: correct pgoutput action parsing for tables named INSERT_LOG
feat: add CUBE explosion guard (max 64 UNION ALL branches)
docs: document JOIN key change limitation in SQL_REFERENCE
test: add E2E test for keyless table duplicate-row behaviour

License

By contributing you agree that your contributions will be licensed under the Apache License 2.0.