dbkit-sql 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. dbkit_sql-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +81 -0
  2. dbkit_sql-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. dbkit_sql-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml +27 -0
  4. dbkit_sql-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +20 -0
  5. dbkit_sql-0.1.0/.github/dependabot.yml +21 -0
  6. dbkit_sql-0.1.0/.github/workflows/ci.yml +116 -0
  7. dbkit_sql-0.1.0/.github/workflows/dependency-matrix.yml +51 -0
  8. dbkit_sql-0.1.0/.github/workflows/docs.yml +47 -0
  9. dbkit_sql-0.1.0/.github/workflows/release.yml +49 -0
  10. dbkit_sql-0.1.0/.github/workflows/security.yml +61 -0
  11. dbkit_sql-0.1.0/.gitignore +16 -0
  12. dbkit_sql-0.1.0/CHANGELOG.md +354 -0
  13. dbkit_sql-0.1.0/CONTRIBUTING.md +32 -0
  14. dbkit_sql-0.1.0/LICENSE +21 -0
  15. dbkit_sql-0.1.0/Makefile +59 -0
  16. dbkit_sql-0.1.0/PKG-INFO +555 -0
  17. dbkit_sql-0.1.0/README.md +491 -0
  18. dbkit_sql-0.1.0/SECURITY.md +70 -0
  19. dbkit_sql-0.1.0/benchmarks/__init__.py +8 -0
  20. dbkit_sql-0.1.0/benchmarks/__main__.py +74 -0
  21. dbkit_sql-0.1.0/benchmarks/_common.py +70 -0
  22. dbkit_sql-0.1.0/benchmarks/_results.py +67 -0
  23. dbkit_sql-0.1.0/benchmarks/_stats.py +131 -0
  24. dbkit_sql-0.1.0/benchmarks/bench_batch.py +109 -0
  25. dbkit_sql-0.1.0/benchmarks/bench_batch_collector.py +65 -0
  26. dbkit_sql-0.1.0/benchmarks/bench_concurrency_scaling.py +162 -0
  27. dbkit_sql-0.1.0/benchmarks/bench_crud.py +238 -0
  28. dbkit_sql-0.1.0/benchmarks/bench_latency.py +86 -0
  29. dbkit_sql-0.1.0/benchmarks/bench_observability_overhead.py +161 -0
  30. dbkit_sql-0.1.0/benchmarks/bench_overhead.py +138 -0
  31. dbkit_sql-0.1.0/benchmarks/bench_pgbouncer_compatible.py +119 -0
  32. dbkit_sql-0.1.0/benchmarks/bench_pool_exhaustion.py +92 -0
  33. dbkit_sql-0.1.0/benchmarks/bench_shard_cardinality.py +157 -0
  34. dbkit_sql-0.1.0/benchmarks/bench_streaming_scale.py +129 -0
  35. dbkit_sql-0.1.0/benchmarks/bench_throughput.py +118 -0
  36. dbkit_sql-0.1.0/benchmarks/bench_unnest.py +101 -0
  37. dbkit_sql-0.1.0/benchmarks/check_regression.py +67 -0
  38. dbkit_sql-0.1.0/benchmarks/soak.py +211 -0
  39. dbkit_sql-0.1.0/docker-compose.yml +16 -0
  40. dbkit_sql-0.1.0/docs/api/config.md +23 -0
  41. dbkit_sql-0.1.0/docs/api/database.md +25 -0
  42. dbkit_sql-0.1.0/docs/api/errors.md +9 -0
  43. dbkit_sql-0.1.0/docs/api/integrations.md +17 -0
  44. dbkit_sql-0.1.0/docs/api/observability.md +24 -0
  45. dbkit_sql-0.1.0/docs/api/query.md +33 -0
  46. dbkit_sql-0.1.0/docs/assets/logo.svg +32 -0
  47. dbkit_sql-0.1.0/docs/cli.md +45 -0
  48. dbkit_sql-0.1.0/docs/index.md +98 -0
  49. dbkit_sql-0.1.0/docs/observability.md +162 -0
  50. dbkit_sql-0.1.0/docs/requirements.md +33 -0
  51. dbkit_sql-0.1.0/docs/roadmap.md +152 -0
  52. dbkit_sql-0.1.0/docs/security.md +75 -0
  53. dbkit_sql-0.1.0/docs/testing.md +125 -0
  54. dbkit_sql-0.1.0/docs/troubleshooting.md +174 -0
  55. dbkit_sql-0.1.0/docs/versioning.md +58 -0
  56. dbkit_sql-0.1.0/examples/batch_collector.py +53 -0
  57. dbkit_sql-0.1.0/examples/bulk_insert_upsert.py +106 -0
  58. dbkit_sql-0.1.0/examples/copy_ingest.py +62 -0
  59. dbkit_sql-0.1.0/examples/error_handling.py +124 -0
  60. dbkit_sql-0.1.0/examples/health_and_pool.py +57 -0
  61. dbkit_sql-0.1.0/examples/inbox_idempotent_consumer.py +160 -0
  62. dbkit_sql-0.1.0/examples/opentelemetry_observability.py +117 -0
  63. dbkit_sql-0.1.0/examples/pgbouncer_mode.py +50 -0
  64. dbkit_sql-0.1.0/examples/pipeline_mode.py +73 -0
  65. dbkit_sql-0.1.0/examples/quickstart_async.py +75 -0
  66. dbkit_sql-0.1.0/examples/quickstart_sync.py +58 -0
  67. dbkit_sql-0.1.0/examples/retries_and_circuit_breaker.py +117 -0
  68. dbkit_sql-0.1.0/examples/run_all.py +59 -0
  69. dbkit_sql-0.1.0/examples/streaming.py +61 -0
  70. dbkit_sql-0.1.0/examples/streaming_checkpoint_resume.py +146 -0
  71. dbkit_sql-0.1.0/examples/sync_feature_parity.py +75 -0
  72. dbkit_sql-0.1.0/examples/transactions_savepoints.py +70 -0
  73. dbkit_sql-0.1.0/mkdocs.yml +92 -0
  74. dbkit_sql-0.1.0/pyproject.toml +116 -0
  75. dbkit_sql-0.1.0/src/dbkit/__init__.py +77 -0
  76. dbkit_sql-0.1.0/src/dbkit/_async/__init__.py +17 -0
  77. dbkit_sql-0.1.0/src/dbkit/_async/_compat.py +111 -0
  78. dbkit_sql-0.1.0/src/dbkit/_async/connection.py +328 -0
  79. dbkit_sql-0.1.0/src/dbkit/_async/database.py +884 -0
  80. dbkit_sql-0.1.0/src/dbkit/_async/engine.py +232 -0
  81. dbkit_sql-0.1.0/src/dbkit/_async/executor.py +329 -0
  82. dbkit_sql-0.1.0/src/dbkit/_async/health.py +53 -0
  83. dbkit_sql-0.1.0/src/dbkit/_async/resilience.py +148 -0
  84. dbkit_sql-0.1.0/src/dbkit/_async/streaming.py +137 -0
  85. dbkit_sql-0.1.0/src/dbkit/_async/transaction.py +264 -0
  86. dbkit_sql-0.1.0/src/dbkit/_core/__init__.py +1 -0
  87. dbkit_sql-0.1.0/src/dbkit/_core/bulk.py +91 -0
  88. dbkit_sql-0.1.0/src/dbkit/_core/circuit.py +130 -0
  89. dbkit_sql-0.1.0/src/dbkit/_core/config.py +613 -0
  90. dbkit_sql-0.1.0/src/dbkit/_core/errors/__init__.py +74 -0
  91. dbkit_sql-0.1.0/src/dbkit/_core/errors/base.py +344 -0
  92. dbkit_sql-0.1.0/src/dbkit/_core/errors/classifier.py +138 -0
  93. dbkit_sql-0.1.0/src/dbkit/_core/errors/redaction.py +96 -0
  94. dbkit_sql-0.1.0/src/dbkit/_core/errors/sqlstate.py +74 -0
  95. dbkit_sql-0.1.0/src/dbkit/_core/idempotency_lint.py +57 -0
  96. dbkit_sql-0.1.0/src/dbkit/_core/keys.py +29 -0
  97. dbkit_sql-0.1.0/src/dbkit/_core/policies.py +105 -0
  98. dbkit_sql-0.1.0/src/dbkit/_core/query.py +142 -0
  99. dbkit_sql-0.1.0/src/dbkit/_core/result.py +109 -0
  100. dbkit_sql-0.1.0/src/dbkit/_core/routing.py +248 -0
  101. dbkit_sql-0.1.0/src/dbkit/_pool.py +202 -0
  102. dbkit_sql-0.1.0/src/dbkit/_sync/__init__.py +20 -0
  103. dbkit_sql-0.1.0/src/dbkit/_sync/_compat.py +82 -0
  104. dbkit_sql-0.1.0/src/dbkit/_sync/connection.py +331 -0
  105. dbkit_sql-0.1.0/src/dbkit/_sync/database.py +887 -0
  106. dbkit_sql-0.1.0/src/dbkit/_sync/engine.py +235 -0
  107. dbkit_sql-0.1.0/src/dbkit/_sync/executor.py +332 -0
  108. dbkit_sql-0.1.0/src/dbkit/_sync/health.py +56 -0
  109. dbkit_sql-0.1.0/src/dbkit/_sync/resilience.py +151 -0
  110. dbkit_sql-0.1.0/src/dbkit/_sync/streaming.py +140 -0
  111. dbkit_sql-0.1.0/src/dbkit/_sync/transaction.py +267 -0
  112. dbkit_sql-0.1.0/src/dbkit/cli/__init__.py +1 -0
  113. dbkit_sql-0.1.0/src/dbkit/cli/main.py +256 -0
  114. dbkit_sql-0.1.0/src/dbkit/errors.py +6 -0
  115. dbkit_sql-0.1.0/src/dbkit/integrations/__init__.py +21 -0
  116. dbkit_sql-0.1.0/src/dbkit/integrations/batch.py +81 -0
  117. dbkit_sql-0.1.0/src/dbkit/integrations/inbox.py +153 -0
  118. dbkit_sql-0.1.0/src/dbkit/observability/__init__.py +21 -0
  119. dbkit_sql-0.1.0/src/dbkit/observability/logging.py +154 -0
  120. dbkit_sql-0.1.0/src/dbkit/observability/metrics.py +110 -0
  121. dbkit_sql-0.1.0/src/dbkit/observability/otel_metrics.py +69 -0
  122. dbkit_sql-0.1.0/src/dbkit/observability/prometheus.py +78 -0
  123. dbkit_sql-0.1.0/src/dbkit/observability/tracing.py +128 -0
  124. dbkit_sql-0.1.0/src/dbkit/postgres/__init__.py +1 -0
  125. dbkit_sql-0.1.0/src/dbkit/postgres/copy.py +77 -0
  126. dbkit_sql-0.1.0/src/dbkit/postgres/pipeline.py +48 -0
  127. dbkit_sql-0.1.0/src/dbkit/postgres/unnest.py +73 -0
  128. dbkit_sql-0.1.0/src/dbkit/testing/__init__.py +1 -0
  129. dbkit_sql-0.1.0/tests/__init__.py +0 -0
  130. dbkit_sql-0.1.0/tests/conftest.py +93 -0
  131. dbkit_sql-0.1.0/tests/integration/__init__.py +0 -0
  132. dbkit_sql-0.1.0/tests/integration/_mp_budget_worker.py +58 -0
  133. dbkit_sql-0.1.0/tests/integration/test_async_integration.py +432 -0
  134. dbkit_sql-0.1.0/tests/integration/test_cli_integration.py +66 -0
  135. dbkit_sql-0.1.0/tests/integration/test_multiprocess_connection_budget.py +119 -0
  136. dbkit_sql-0.1.0/tests/integration/test_resilience_scenarios.py +838 -0
  137. dbkit_sql-0.1.0/tests/integration/test_sharding_and_replicas.py +179 -0
  138. dbkit_sql-0.1.0/tests/integration/test_sync_integration.py +188 -0
  139. dbkit_sql-0.1.0/tests/integration/test_throughput_paths.py +415 -0
  140. dbkit_sql-0.1.0/tests/property/__init__.py +0 -0
  141. dbkit_sql-0.1.0/tests/property/test_invariants.py +217 -0
  142. dbkit_sql-0.1.0/tests/security/__init__.py +0 -0
  143. dbkit_sql-0.1.0/tests/security/test_redaction.py +85 -0
  144. dbkit_sql-0.1.0/tests/security/test_sql_injection.py +49 -0
  145. dbkit_sql-0.1.0/tests/unit/__init__.py +0 -0
  146. dbkit_sql-0.1.0/tests/unit/test_benchmark_stats.py +81 -0
  147. dbkit_sql-0.1.0/tests/unit/test_bulk_batch.py +108 -0
  148. dbkit_sql-0.1.0/tests/unit/test_cancellation_shielding.py +75 -0
  149. dbkit_sql-0.1.0/tests/unit/test_circuit.py +57 -0
  150. dbkit_sql-0.1.0/tests/unit/test_cli.py +168 -0
  151. dbkit_sql-0.1.0/tests/unit/test_config.py +290 -0
  152. dbkit_sql-0.1.0/tests/unit/test_dual_api.py +56 -0
  153. dbkit_sql-0.1.0/tests/unit/test_engine_registry.py +165 -0
  154. dbkit_sql-0.1.0/tests/unit/test_errors.py +90 -0
  155. dbkit_sql-0.1.0/tests/unit/test_idempotency_lint.py +54 -0
  156. dbkit_sql-0.1.0/tests/unit/test_logging.py +83 -0
  157. dbkit_sql-0.1.0/tests/unit/test_otel_metrics.py +76 -0
  158. dbkit_sql-0.1.0/tests/unit/test_policies.py +82 -0
  159. dbkit_sql-0.1.0/tests/unit/test_prometheus_metrics.py +84 -0
  160. dbkit_sql-0.1.0/tests/unit/test_query.py +60 -0
  161. dbkit_sql-0.1.0/tests/unit/test_resilience.py +297 -0
  162. dbkit_sql-0.1.0/tests/unit/test_result.py +84 -0
  163. dbkit_sql-0.1.0/tests/unit/test_sharding_replica.py +172 -0
  164. dbkit_sql-0.1.0/tests/unit/test_tracing.py +134 -0
  165. dbkit_sql-0.1.0/tests/unit/test_unasync_translation.py +108 -0
  166. dbkit_sql-0.1.0/tests/unit/test_unnest.py +61 -0
  167. dbkit_sql-0.1.0/tools/run_unasync.py +171 -0
@@ -0,0 +1,81 @@
1
+ name: Bug report
2
+ description: Report a bug in dbkit
3
+ labels: ["bug"]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ Thanks for taking the time to report a bug. Please do **not** use this
9
+ template for security vulnerabilities — see
10
+ [SECURITY.md](https://github.com/talaatmagdyx/dbkit-sql/blob/main/SECURITY.md)
11
+ instead.
12
+
13
+ - type: input
14
+ id: version
15
+ attributes:
16
+ label: dbkit-sql version
17
+ placeholder: "0.1.0"
18
+ validations:
19
+ required: true
20
+
21
+ - type: dropdown
22
+ id: frontend
23
+ attributes:
24
+ label: Frontend
25
+ options:
26
+ - async (AsyncDatabase)
27
+ - sync (Database)
28
+ - both / not frontend-specific
29
+ validations:
30
+ required: true
31
+
32
+ - type: dropdown
33
+ id: driver
34
+ attributes:
35
+ label: Driver
36
+ options:
37
+ - psycopg (default)
38
+ - asyncpg
39
+ - other / not driver-specific
40
+ validations:
41
+ required: true
42
+
43
+ - type: textarea
44
+ id: what-happened
45
+ attributes:
46
+ label: What happened?
47
+ description: A clear description of the bug, including any stack trace.
48
+ validations:
49
+ required: true
50
+
51
+ - type: textarea
52
+ id: expected
53
+ attributes:
54
+ label: Expected behavior
55
+ validations:
56
+ required: true
57
+
58
+ - type: textarea
59
+ id: repro
60
+ attributes:
61
+ label: Minimal reproduction
62
+ description: |
63
+ A minimal script (ideally runnable against a disposable PostgreSQL, e.g.
64
+ via testcontainers) that reproduces the issue. This is the single most
65
+ useful thing you can provide.
66
+ render: python
67
+ validations:
68
+ required: false
69
+
70
+ - type: textarea
71
+ id: environment
72
+ attributes:
73
+ label: Environment
74
+ description: Python version, OS, PostgreSQL version, SQLAlchemy version.
75
+ placeholder: |
76
+ - Python: 3.12.2
77
+ - OS: Ubuntu 22.04
78
+ - PostgreSQL: 16
79
+ - SQLAlchemy: 2.0.32
80
+ validations:
81
+ required: false
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Security vulnerability
4
+ url: https://github.com/talaatmagdyx/dbkit-sql/security/advisories/new
5
+ about: Please report security vulnerabilities privately — see SECURITY.md. Do not open a public issue.
@@ -0,0 +1,27 @@
1
+ name: Feature request
2
+ description: Suggest an enhancement for dbkit
3
+ labels: ["enhancement"]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: What problem does this solve?
9
+ description: Describe the use case — what are you trying to do that dbkit doesn't support today?
10
+ validations:
11
+ required: true
12
+
13
+ - type: textarea
14
+ id: proposal
15
+ attributes:
16
+ label: Proposed API / behavior
17
+ description: Sketch the API you'd expect, if you have one in mind.
18
+ render: python
19
+ validations:
20
+ required: false
21
+
22
+ - type: textarea
23
+ id: alternatives
24
+ attributes:
25
+ label: Alternatives considered
26
+ validations:
27
+ required: false
@@ -0,0 +1,20 @@
1
+ ## Summary
2
+
3
+ <!-- What does this PR change, and why? Link the issue it addresses. -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] `make lint` passes (`ruff check` + `ruff format --check`)
8
+ - [ ] `make type` passes (`mypy --strict`)
9
+ - [ ] `make test` passes (unit + property + security, no database)
10
+ - [ ] Edited `src/dbkit/_async/` only — never hand-edited `src/dbkit/_sync/`;
11
+ ran `make unasync` so the generated sync code is in sync (CI fails on drift)
12
+ - [ ] Tests added/updated (`tests/unit/…` and/or `tests/integration/…`)
13
+ - [ ] `CHANGELOG.md` updated under `[Unreleased]`
14
+ - [ ] `README.md` / `docs/` updated (if user-facing)
15
+ - [ ] If this touches SQL execution, transactions, pooling, or routing, verified
16
+ against `tests/integration/` (real PostgreSQL via `DBKIT_TEST_DSN`/testcontainers)
17
+
18
+ ## Test plan
19
+
20
+ <!-- How did you verify this? What did you run, and what did it prove? -->
@@ -0,0 +1,21 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: "pip"
4
+ directory: "/"
5
+ schedule:
6
+ interval: "weekly"
7
+ open-pull-requests-limit: 10
8
+ groups:
9
+ dev-dependencies:
10
+ patterns:
11
+ - "pytest*"
12
+ - "mypy"
13
+ - "ruff"
14
+ - "mkdocs*"
15
+ - "hypothesis"
16
+ - "testcontainers"
17
+
18
+ - package-ecosystem: "github-actions"
19
+ directory: "/"
20
+ schedule:
21
+ interval: "weekly"
@@ -0,0 +1,116 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ci-${{ github.ref }}
10
+ cancel-in-progress: true
11
+
12
+ jobs:
13
+ static:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: astral-sh/setup-uv@v3
18
+ - run: uv python install 3.12
19
+ - run: uv sync --extra dev
20
+ - name: unasync drift check
21
+ run: uv run python tools/run_unasync.py --check
22
+ - run: uv run ruff check src tests benchmarks examples
23
+ - run: uv run ruff format --check src tests examples
24
+ - run: uv run mypy
25
+ - name: docs site builds
26
+ run: uv run mkdocs build --strict
27
+ - name: package builds and passes metadata checks
28
+ run: |
29
+ uv run python -m build
30
+ uv run twine check dist/*
31
+
32
+ unit:
33
+ runs-on: ubuntu-latest
34
+ strategy:
35
+ fail-fast: false
36
+ matrix:
37
+ python: ["3.11", "3.12", "3.13"]
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+ - uses: astral-sh/setup-uv@v3
41
+ - run: uv python install ${{ matrix.python }}
42
+ - run: uv sync --extra dev
43
+ - run: uv run pytest -q -m "not integration" --cov=dbkit --cov-report=term-missing
44
+
45
+ integration:
46
+ runs-on: ubuntu-latest
47
+ services:
48
+ postgres:
49
+ image: postgres:16
50
+ env:
51
+ POSTGRES_USER: dbkit
52
+ POSTGRES_PASSWORD: dbkit
53
+ POSTGRES_DB: dbkit
54
+ ports: ["5432:5432"]
55
+ options: >-
56
+ --health-cmd "pg_isready -U dbkit"
57
+ --health-interval 2s --health-timeout 3s --health-retries 15
58
+ env:
59
+ DBKIT_TEST_DSN: postgresql+psycopg://dbkit:dbkit@localhost:5432/dbkit
60
+ steps:
61
+ - uses: actions/checkout@v4
62
+ - uses: astral-sh/setup-uv@v3
63
+ - run: uv python install 3.12
64
+ - run: uv sync --extra dev
65
+ - name: integration + chaos/resilience suite
66
+ run: uv run pytest -q -m integration
67
+ - name: short soak with fault injection (leak/recovery gate)
68
+ run: uv run python -m benchmarks.soak --dsn "$DBKIT_TEST_DSN" --duration 60 --kill-every 20
69
+ - name: performance regression gate (overhead ceiling + pool-exhaustion contract)
70
+ run: uv run python -m benchmarks.check_regression --dsn "$DBKIT_TEST_DSN"
71
+ - name: benchmark smoke (best-effort, non-gating)
72
+ run: uv run python -m benchmarks --dsn "$DBKIT_TEST_DSN" --no-save || echo "benchmarks best-effort"
73
+
74
+ integration-asyncpg:
75
+ # asyncpg is async-only (no sync engine support) and doesn't implement the psycopg-only raw
76
+ # driver escape hatches (COPY, pipeline mode, PgBouncer autoprep control) — those tests
77
+ # self-skip via the `requires_psycopg` fixture. This job covers everything else: CRUD,
78
+ # transactions/savepoints, cardinality, resilience/chaos, sharding/replicas, and the CLI.
79
+ runs-on: ubuntu-latest
80
+ services:
81
+ postgres:
82
+ image: postgres:16
83
+ env:
84
+ POSTGRES_USER: dbkit
85
+ POSTGRES_PASSWORD: dbkit
86
+ POSTGRES_DB: dbkit
87
+ ports: ["5432:5432"]
88
+ options: >-
89
+ --health-cmd "pg_isready -U dbkit"
90
+ --health-interval 2s --health-timeout 3s --health-retries 15
91
+ env:
92
+ DBKIT_TEST_DSN: postgresql+asyncpg://dbkit:dbkit@localhost:5432/dbkit
93
+ steps:
94
+ - uses: actions/checkout@v4
95
+ - uses: astral-sh/setup-uv@v3
96
+ - run: uv python install 3.12
97
+ - run: uv sync --extra dev
98
+ - name: async-only integration + chaos/resilience suite
99
+ run: uv run pytest -q -m integration --ignore=tests/integration/test_sync_integration.py
100
+
101
+ all-checks:
102
+ # A single required status for branch protection, instead of listing every job above
103
+ # individually (which breaks whenever a job is renamed/added/removed).
104
+ name: All checks passed
105
+ runs-on: ubuntu-latest
106
+ needs: [static, unit, integration, integration-asyncpg]
107
+ if: always()
108
+ steps:
109
+ - name: Fail if any required job did not succeed
110
+ run: |
111
+ if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" || \
112
+ "${{ contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
113
+ echo "One or more required jobs failed or were cancelled."
114
+ exit 1
115
+ fi
116
+ echo "All required jobs passed."
@@ -0,0 +1,51 @@
1
+ # dbkit pins its runtime deps to floors (sqlalchemy>=2.0.30, psycopg>=3.2,
2
+ # asyncpg>=0.29 — see pyproject.toml) but the regular CI jobs only ever install
3
+ # whatever pip currently resolves within those ranges, which drifts toward
4
+ # "latest" over time and never actually exercises the pinned MINIMUM. This job
5
+ # tests both ends of each range nightly, against a real PostgreSQL, so a real
6
+ # incompatibility at either boundary is caught before a user hits it.
7
+ name: Dependency matrix
8
+
9
+ on:
10
+ schedule:
11
+ # Nightly, 02:00 UTC.
12
+ - cron: "0 2 * * *"
13
+ workflow_dispatch: {}
14
+
15
+ permissions:
16
+ contents: read
17
+
18
+ jobs:
19
+ dependency-matrix:
20
+ runs-on: ubuntu-latest
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ sqlalchemy-version: ["2.0.30", "latest"]
25
+ driver-floor: ["floor", "latest"]
26
+ services:
27
+ postgres:
28
+ image: postgres:16
29
+ env:
30
+ POSTGRES_USER: dbkit
31
+ POSTGRES_PASSWORD: dbkit
32
+ POSTGRES_DB: dbkit
33
+ ports: ["5432:5432"]
34
+ options: >-
35
+ --health-cmd "pg_isready -U dbkit"
36
+ --health-interval 2s --health-timeout 3s --health-retries 15
37
+ env:
38
+ DBKIT_TEST_DSN: postgresql+psycopg://dbkit:dbkit@localhost:5432/dbkit
39
+ steps:
40
+ - uses: actions/checkout@v4
41
+ - uses: astral-sh/setup-uv@v3
42
+ - run: uv python install 3.12
43
+ - run: uv sync --extra dev
44
+ - name: Pin SQLAlchemy to matrix version
45
+ if: matrix.sqlalchemy-version != 'latest'
46
+ run: uv pip install "sqlalchemy[asyncio]==${{ matrix.sqlalchemy-version }}"
47
+ - name: Pin drivers to their floors
48
+ if: matrix.driver-floor == 'floor'
49
+ run: uv pip install "psycopg[binary]==3.2.0" "asyncpg==0.29.0"
50
+ - name: Unit + integration suite
51
+ run: uv run pytest -q
@@ -0,0 +1,47 @@
1
+ name: Deploy Docs
2
+
3
+ # Builds the mkdocs site and publishes it to GitHub Pages via the "GitHub Actions" Pages source
4
+ # (no gh-pages branch needed). One-time manual setup required before this can deploy: in the
5
+ # repo's Settings > Pages, set "Build and deployment > Source" to "GitHub Actions".
6
+
7
+ on:
8
+ push:
9
+ branches: [main]
10
+ paths:
11
+ - docs/**
12
+ - mkdocs.yml
13
+ - src/dbkit/**
14
+ - .github/workflows/docs.yml
15
+ workflow_dispatch:
16
+
17
+ permissions:
18
+ contents: read
19
+ pages: write
20
+ id-token: write
21
+
22
+ concurrency:
23
+ group: pages
24
+ cancel-in-progress: false
25
+
26
+ jobs:
27
+ build:
28
+ runs-on: ubuntu-latest
29
+ steps:
30
+ - uses: actions/checkout@v4
31
+ - uses: astral-sh/setup-uv@v3
32
+ - run: uv python install 3.12
33
+ - run: uv sync --extra dev
34
+ - run: uv run mkdocs build --strict
35
+ - uses: actions/upload-pages-artifact@v3
36
+ with:
37
+ path: site
38
+
39
+ deploy:
40
+ needs: build
41
+ runs-on: ubuntu-latest
42
+ environment:
43
+ name: github-pages
44
+ url: ${{ steps.deployment.outputs.page_url }}
45
+ steps:
46
+ - id: deployment
47
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,49 @@
1
+ name: Release
2
+
3
+ # Triggered by pushing a version tag, e.g. `git tag v0.1.0 && git push --tags`.
4
+ # Uses PyPI's trusted publishing (OIDC) — no API token stored in this repo. Configure the
5
+ # trusted publisher for this repo/workflow at
6
+ # https://pypi.org/manage/project/dbkit-sql/settings/publishing/ before the first release
7
+ # (the project must already exist on PyPI, or use the "pending publisher" flow for a
8
+ # not-yet-published project at https://pypi.org/manage/account/publishing/).
9
+ on:
10
+ push:
11
+ tags:
12
+ - "v*.*.*"
13
+
14
+ jobs:
15
+ build:
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: astral-sh/setup-uv@v3
20
+ - run: uv python install 3.12
21
+ - run: uv sync --extra dev
22
+ - name: full gate before release
23
+ run: |
24
+ uv run python tools/run_unasync.py --check
25
+ uv run ruff check src tests benchmarks
26
+ uv run ruff format --check src tests
27
+ uv run mypy
28
+ uv run pytest -q -m "not integration"
29
+ - name: build sdist and wheel
30
+ run: uv run python -m build
31
+ - name: verify package metadata
32
+ run: uv run twine check dist/*
33
+ - uses: actions/upload-artifact@v4
34
+ with:
35
+ name: dist
36
+ path: dist/
37
+
38
+ publish:
39
+ needs: build
40
+ runs-on: ubuntu-latest
41
+ environment: pypi
42
+ permissions:
43
+ id-token: write # required for trusted publishing
44
+ steps:
45
+ - uses: actions/download-artifact@v4
46
+ with:
47
+ name: dist
48
+ path: dist/
49
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,61 @@
1
+ # Dependency vulnerability scanning + static analysis + SBOM.
2
+ #
3
+ # - `pip-audit` checks installed dependencies against the OSV/PyPA advisory
4
+ # databases and fails the job on a known vulnerability.
5
+ # - CodeQL performs static analysis on the Python source for common security
6
+ # issues (injection, unsafe deserialization, etc.).
7
+ # - pip-audit's CycloneDX exporter produces a software bill of materials
8
+ # (every installed dependency + version) as a build artifact, generated
9
+ # only after the audit step above passes.
10
+ #
11
+ # All run on every push/PR to main and on a weekly schedule so a newly
12
+ # disclosed CVE in an existing dependency is caught even without a code
13
+ # change.
14
+ name: Security
15
+
16
+ on:
17
+ push:
18
+ branches: [main]
19
+ pull_request:
20
+ branches: [main]
21
+ schedule:
22
+ # Weekly, Monday 04:00 UTC.
23
+ - cron: "0 4 * * 1"
24
+
25
+ permissions:
26
+ contents: read
27
+
28
+ jobs:
29
+ pip-audit:
30
+ runs-on: ubuntu-latest
31
+ steps:
32
+ - uses: actions/checkout@v4
33
+ - uses: astral-sh/setup-uv@v3
34
+ - run: uv python install 3.12
35
+ - run: uv sync --extra dev
36
+ - name: pip-audit
37
+ run: |
38
+ uv pip install pip-audit
39
+ # --skip-editable: dbkit itself is installed editable and (until the
40
+ # first PyPI release is public) can't be audited against the advisory
41
+ # DBs. No --strict: it escalates that (intentional) skip to an error;
42
+ # known vulnerabilities still fail the job without it.
43
+ uv run python -m pip_audit --skip-editable
44
+ - name: Generate SBOM (CycloneDX)
45
+ run: uv run python -m pip_audit --skip-editable --format=cyclonedx-json --output=sbom.json
46
+ - uses: actions/upload-artifact@v4
47
+ with:
48
+ name: sbom
49
+ path: sbom.json
50
+
51
+ codeql:
52
+ runs-on: ubuntu-latest
53
+ permissions:
54
+ contents: read
55
+ security-events: write
56
+ steps:
57
+ - uses: actions/checkout@v4
58
+ - uses: github/codeql-action/init@v3
59
+ with:
60
+ languages: python
61
+ - uses: github/codeql-action/analyze@v3
@@ -0,0 +1,16 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .mypy_cache/
5
+ .ruff_cache/
6
+ .coverage
7
+ htmlcov/
8
+ dist/
9
+ build/
10
+ *.egg-info/
11
+ .venv/
12
+ uv.lock
13
+ .DS_Store
14
+ .hypothesis/
15
+ benchmarks/results/
16
+ site/