pgcommon 0.1.0__tar.gz

pgcommon-0.1.0/.env-example

@@ -0,0 +1,28 @@
+# Copy to .env for local development: `make setup` does this for you.
+
+# Either set DATABASE_URL directly...
+DATABASE_URL=postgres://test:test@localhost:5432/test
+
+# ...or the individual PG_* variables (used only when DATABASE_URL is unset):
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=test
+PG_PASSWORD=test
+PG_DBNAME=test
+PG_SSLMODE=disable
+PG_BOUNCER_MODE=false
+
+# Pool tuning (all optional — see README.md's Configuration reference for defaults).
+PG_MAX_CONNS=10
+PG_MIN_CONNS=2
+PG_MAX_CONN_LIFETIME=1h
+PG_MAX_CONN_LIFETIME_JITTER=0
+PG_MAX_CONN_IDLE_TIME=30m
+PG_HEALTH_CHECK_PERIOD=1m
+PG_SLOW_QUERY_THRESHOLD=200ms
+
+# PgBouncer, if using `make docker-up-all`.
+PGBOUNCER_DATABASE_URL=postgres://test:test@localhost:6432/test
+
+APP_NAME=pgcommon-dev
+BUILD_VERSION=0.0.0-dev

pgcommon-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Default: every file requires review from the platform team.
+# Replace @BCBP-SOLUTIONS-FZC-LLC/platform-team with your actual team slug.
+* @BCBP-SOLUTIONS-FZC-LLC/platform-team
+
+# Workflow and release automation changes require explicit sign-off.
+.github/workflows/ @BCBP-SOLUTIONS-FZC-LLC/platform-team
+.github/dependabot.yml @BCBP-SOLUTIONS-FZC-LLC/platform-team
+
+# Public API surface — extra scrutiny.
+src/pgcommon/ @BCBP-SOLUTIONS-FZC-LLC/platform-team

pgcommon-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Report a defect in pgcommon
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear description of the bug.
+
+## Library version
+`pgcommon==X.Y.Z`
+
+## Python version
+`python --version` output
+
+## Configuration
+Relevant `Config` fields (redact the DSN's credentials): `pgbouncer_mode`, `guc_provider` set?, `max_conns`/`min_conns`, etc.
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behaviour
+What you expected to happen.
+
+## Actual behaviour
+What actually happened. Include error messages, stack traces, or log output.
+
+## Minimal reproduction
+```python
+# paste the smallest Python snippet that triggers the bug
+```
+
+## Additional context
+Any other relevant context (direct Postgres vs. PgBouncer/RDS Proxy, OS, container environment, related issues).

pgcommon-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Propose a new helper, config option, or enhancement
+title: '[FEAT] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem / motivation
+What problem does this solve? Who is affected?
+
+## Proposed solution
+Describe the API or behaviour change you'd like.
+
+```python
+# Example usage of the proposed feature
+```
+
+## Alternatives considered
+Other approaches you evaluated and why you ruled them out.
+
+## Acceptance criteria
+- [ ]
+- [ ]
+- [ ]
+
+## Additional context
+Links to related issues, the equivalent Go `platform-pgcommon` behavior (if any), or prior art.

pgcommon-0.1.0/.github/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.x     | ✅ Active |
+
+Older major versions are not patched. Upgrade to the latest 0.x release. See [../VERSIONING.md](../VERSIONING.md) for the full policy once `1.0.0` ships.
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Email: vijay@bcbpsolutions.com
+
+Include in your report:
+- Description of the vulnerability and affected component
+- Steps to reproduce
+- Potential impact (tenant data isolation bypass, credential leakage, DoS, etc.)
+- Suggested fix or patch (if any)
+
+### Response timeline
+
+| Step | Target |
+|------|--------|
+| Initial acknowledgement | 48 hours |
+| Severity assessment | 5 business days |
+| Patch release (critical/high) | 14 days |
+| Public disclosure | After patch ships |
+
+We follow responsible disclosure. We will credit reporters in the release notes unless anonymity is requested.
+
+See [../SECURITY.md](../SECURITY.md) for this library's trust model and known sensitive surface area (GUC injection, `contextvars` propagation, DSN masking).

pgcommon-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, python]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, github-actions]
+
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, docker]

pgcommon-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,62 @@
+## Description
+Provide a clear description of the changes.
+
+---
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Test
+- [ ] Breaking change
+
+---
+
+## Testing
+- [ ] Unit tests added/updated (`make test-unit` — no Docker required)
+- [ ] Integration/e2e tests added/updated if this touches GUC injection, transaction/rollback semantics, PgBouncer mode, or the migration runner (`make test-int` / `make test-e2e`)
+- [ ] All tests passing (`make cover` — full suite, ≥97% coverage gate)
+- [ ] Manual testing performed (if required)
+
+---
+
+## Checklist
+
+### Code Quality
+- [ ] Code is properly formatted (`make format` — ruff format)
+- [ ] Linting passed (`make lint` — ruff)
+- [ ] Type checking passed (`make typecheck` — mypy --strict)
+- [ ] No debug logs / commented code
+
+---
+
+### Tenancy & safety (IMPORTANT for this library)
+- [ ] Any change touching GUC injection timing or scope (`pgcommon.guc`, `pgcommon.pool`, `pgcommon.tx`) has an integration/e2e test — see `tests/integration/test_rls_guc_injection.py` and `tests/e2e/test_rls_pgbouncer_e2e.py` for the pattern
+- [ ] All database access still goes through `Pool.with_conn`/`run_in_tx` — no new path exposes a raw `asyncpg.Pool` or `Connection`
+- [ ] `contextvars.ContextVar.set()` calls are paired with a `reset()` in a `finally`/context manager (see ARCHITECTURE.md's concurrency notes) — a missing pairing is the most likely cause of a cross-request GUC leak
+- [ ] Retry-eligible code paths (`pgcommon.retry`) are only added for genuinely idempotent operations
+
+---
+
+### Security
+- [ ] No secrets hardcoded
+- [ ] `pgcommon._internal` is not imported from outside `src/pgcommon/` (enforced by `ruff`, but check anyway)
+- [ ] `log_tenant_id`/`allow_full_statements` default behavior (opt-in only) is unaffected, or the change to it is deliberate and documented
+
+---
+
+### Documentation
+- [ ] README updated (config/error reference tables, pitfalls) if the public API changed
+- [ ] `ARCHITECTURE.md` updated if a cross-cutting design decision or an asyncio/Go behavioral divergence changed
+- [ ] `CHANGELOG.md`'s `[Unreleased]` section updated
+
+---
+
+## 🔗 Related Issue
+Closes #<issue-id>
+
+---
+
+## Deployment Notes
+Mention anything important for deployment (e.g. a required migration, a config default change).

pgcommon-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,319 @@
+# CI for https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
+name: CI
+
+"on":
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate
+    uses: ./.github/workflows/validate.yml
+
+  coverage:
+    name: Coverage (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: validate
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies (uv sync from uv.lock)
+        run: uv sync
+
+      - name: Test with coverage (>=97% required, enforced by pyproject.toml)
+        run: uv run pytest
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: coverage-report-py${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: ignore
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: coverage
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify build artifacts
+        run: ls dist/*.whl dist/*.tar.gz
+
+      - name: Verify the pgcommon-migrate console script installs and runs
+        run: |
+          python3 -m venv /tmp/verify-venv
+          /tmp/verify-venv/bin/pip install --quiet dist/*.whl
+          /tmp/verify-venv/bin/pgcommon-migrate --help
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: pgcommon-dist
+          path: dist/
+          if-no-files-found: error
+
+  lint-dockerfile:
+    name: Lint Dockerfile
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run hadolint
+        uses: hadolint/hadolint-action@v3.3.0
+        with:
+          dockerfile: Dockerfile
+          failure-threshold: warning
+
+  build-image:
+    name: Build image (cache)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build (no push)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          tags: pgcommon-migrate:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  trivy-scan:
+    name: Trivy CVE scan
+    runs-on: ubuntu-latest
+    needs: build-image
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      # Rebuilds against the GHA cache populated by "Build image (cache)" — fast, and
+      # keeps this job self-contained (no cross-job image tarball transfer needed).
+      - name: Build image (load, cached)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          load: true
+          tags: pgcommon-migrate:ci
+          cache-from: type=gha
+
+      - name: Run Trivy vulnerability scan
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: pgcommon-migrate:ci
+          format: table
+          severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          exit-code: '1'
+          scanners: vuln
+
+  smoke-tests:
+    name: Smoke tests
+    runs-on: ubuntu-latest
+    needs: build-image
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build image (load, cached)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          load: true
+          tags: pgcommon-migrate:ci
+          cache-from: type=gha
+
+      # This image is a migrate CLI, not a running service — "smoke test" means: the
+      # entrypoint runs and prints usage, and a real invocation against a bad/missing
+      # migration source fails cleanly (non-zero exit, readable error), rather than
+      # hanging or crashing with a traceback.
+      - name: Default CMD prints usage
+        run: docker run --rm pgcommon-migrate:ci | grep -q 'Apply or roll back pgcommon SQL migrations'
+
+      - name: up fails cleanly against a missing migration source
+        run: |
+          set +e
+          output=$(docker run --rm pgcommon-migrate:ci --dsn "postgres://x" up 2>&1)
+          status=$?
+          set -e
+          echo "$output"
+          [ "$status" -ne 0 ]
+          echo "$output" | grep -q 'migration source'
+
+  docker:
+    name: Docker image (migrate CLI)
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/bcbp-solutions-fzc-llc/platform-pgcommon-py
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build and push image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  pr-summary:
+    name: PR summary
+    runs-on: ubuntu-latest
+    needs: [validate, build-image, lint-dockerfile, trivy-scan, smoke-tests]
+    if: always() && github.event_name == 'pull_request'
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Post summary comment
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const results = {
+              'Validate (Quality + Test)': '${{ needs.validate.result }}',
+              'Build image (cache)': '${{ needs.build-image.result }}',
+              'Lint Dockerfile': '${{ needs.lint-dockerfile.result }}',
+              'Trivy CVE scan': '${{ needs.trivy-scan.result }}',
+              'Smoke tests': '${{ needs.smoke-tests.result }}',
+            };
+            const icon = (r) => (r === 'success' ? '✅' : r === 'skipped' ? '⏭️' : '❌');
+            const rows = Object.entries(results)
+              .map(([name, result]) => `| ${name} | ${icon(result)} ${result} |`)
+              .join('\n');
+            const body = [
+              '### CI summary',
+              '',
+              '| Check | Result |',
+              '|---|---|',
+              rows,
+            ].join('\n');
+
+            const marker = '<!-- pr-summary-bot -->';
+            const fullBody = `${marker}\n${body}`;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find((c) => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: fullBody,
+              });
+            }

pgcommon-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,49 @@
+# Reusable workflow — called by validate.yml's "Quality" job. Its job id ("quality")
+# combines with the calling chain to produce the "Validate / Quality / quality" required
+# status check.
+# Runs: checkout → uv sync (dev group, from uv.lock) → format check → ruff → mypy → pip-audit
+name: Quality Check
+
+"on":
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Git ref to check out (leave empty to use the caller ref)'
+        type: string
+        required: false
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies (uv sync from uv.lock)
+        run: uv sync
+
+      - name: Verify dependency resolution
+        run: uv pip check
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy
+
+      - name: Vulnerability check (pip-audit)
+        run: uv run pip-audit