dbkit-sql 0.1.0__tar.gz → 0.3.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 (181) hide show
  1. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/CHANGELOG.md +72 -0
  2. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/PKG-INFO +31 -4
  3. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/README.md +25 -3
  4. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/api/database.md +17 -0
  5. dbkit_sql-0.3.0/docs/api/integrations.md +79 -0
  6. dbkit_sql-0.3.0/docs/dynamic-registration.md +88 -0
  7. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/index.md +4 -3
  8. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/roadmap.md +3 -2
  9. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/security.md +2 -1
  10. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/testing.md +30 -0
  11. dbkit_sql-0.3.0/examples/advisory_locks.py +42 -0
  12. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/run_all.py +2 -0
  13. dbkit_sql-0.3.0/examples/transactional_outbox.py +71 -0
  14. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/mkdocs.yml +1 -0
  15. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/pyproject.toml +8 -2
  16. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/__init__.py +1 -1
  17. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/connection.py +49 -1
  18. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/database.py +202 -3
  19. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/engine.py +15 -0
  20. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/executor.py +11 -0
  21. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/transaction.py +48 -0
  22. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/config.py +16 -3
  23. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/__init__.py +4 -0
  24. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/base.py +22 -0
  25. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/query.py +6 -0
  26. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/routing.py +20 -0
  27. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/connection.py +49 -1
  28. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/database.py +202 -3
  29. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/engine.py +15 -0
  30. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/executor.py +11 -0
  31. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/transaction.py +48 -0
  32. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/__init__.py +12 -0
  33. dbkit_sql-0.3.0/src/dbkit/integrations/fastapi.py +137 -0
  34. dbkit_sql-0.3.0/src/dbkit/integrations/outbox.py +158 -0
  35. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/metrics.py +16 -0
  36. dbkit_sql-0.3.0/src/dbkit/testing/__init__.py +309 -0
  37. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_async_integration.py +90 -0
  38. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_sync_integration.py +11 -0
  39. dbkit_sql-0.3.0/tests/unit/__init__.py +0 -0
  40. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_cli.py +1 -1
  41. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_config.py +8 -2
  42. dbkit_sql-0.3.0/tests/unit/test_default_metrics_sink.py +42 -0
  43. dbkit_sql-0.3.0/tests/unit/test_dynamic_registration.py +349 -0
  44. dbkit_sql-0.3.0/tests/unit/test_fastapi_integration.py +91 -0
  45. dbkit_sql-0.3.0/tests/unit/test_integrations_outbox.py +70 -0
  46. dbkit_sql-0.3.0/tests/unit/test_query_settings.py +53 -0
  47. dbkit_sql-0.3.0/tests/unit/test_testing_fakes.py +78 -0
  48. dbkit_sql-0.1.0/docs/api/integrations.md +0 -17
  49. dbkit_sql-0.1.0/src/dbkit/testing/__init__.py +0 -1
  50. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
  51. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  52. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
  53. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  54. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/dependabot.yml +0 -0
  55. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/workflows/ci.yml +0 -0
  56. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/workflows/dependency-matrix.yml +0 -0
  57. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/workflows/docs.yml +0 -0
  58. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/workflows/release.yml +0 -0
  59. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.github/workflows/security.yml +0 -0
  60. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/.gitignore +0 -0
  61. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/CONTRIBUTING.md +0 -0
  62. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/LICENSE +0 -0
  63. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/Makefile +0 -0
  64. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/SECURITY.md +0 -0
  65. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/__init__.py +0 -0
  66. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/__main__.py +0 -0
  67. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/_common.py +0 -0
  68. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/_results.py +0 -0
  69. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/_stats.py +0 -0
  70. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch.py +0 -0
  71. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch_collector.py +0 -0
  72. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_concurrency_scaling.py +0 -0
  73. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_crud.py +0 -0
  74. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_latency.py +0 -0
  75. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_observability_overhead.py +0 -0
  76. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_overhead.py +0 -0
  77. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_pgbouncer_compatible.py +0 -0
  78. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_pool_exhaustion.py +0 -0
  79. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_shard_cardinality.py +0 -0
  80. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_streaming_scale.py +0 -0
  81. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_throughput.py +0 -0
  82. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/bench_unnest.py +0 -0
  83. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/check_regression.py +0 -0
  84. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/benchmarks/soak.py +0 -0
  85. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docker-compose.yml +0 -0
  86. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/api/config.md +0 -0
  87. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/api/errors.md +0 -0
  88. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/api/observability.md +0 -0
  89. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/api/query.md +0 -0
  90. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/assets/logo.svg +0 -0
  91. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/cli.md +0 -0
  92. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/observability.md +0 -0
  93. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/requirements.md +0 -0
  94. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/troubleshooting.md +0 -0
  95. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/docs/versioning.md +0 -0
  96. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/batch_collector.py +0 -0
  97. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/bulk_insert_upsert.py +0 -0
  98. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/copy_ingest.py +0 -0
  99. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/error_handling.py +0 -0
  100. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/health_and_pool.py +0 -0
  101. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/inbox_idempotent_consumer.py +0 -0
  102. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/opentelemetry_observability.py +0 -0
  103. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/pgbouncer_mode.py +0 -0
  104. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/pipeline_mode.py +0 -0
  105. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/quickstart_async.py +0 -0
  106. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/quickstart_sync.py +0 -0
  107. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/retries_and_circuit_breaker.py +0 -0
  108. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/streaming.py +0 -0
  109. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/streaming_checkpoint_resume.py +0 -0
  110. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/sync_feature_parity.py +0 -0
  111. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/examples/transactions_savepoints.py +0 -0
  112. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/__init__.py +0 -0
  113. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/_compat.py +0 -0
  114. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/health.py +0 -0
  115. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/resilience.py +0 -0
  116. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_async/streaming.py +0 -0
  117. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/__init__.py +0 -0
  118. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/bulk.py +0 -0
  119. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/circuit.py +0 -0
  120. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/classifier.py +0 -0
  121. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/redaction.py +0 -0
  122. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/sqlstate.py +0 -0
  123. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/idempotency_lint.py +0 -0
  124. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/keys.py +0 -0
  125. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/policies.py +0 -0
  126. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_core/result.py +0 -0
  127. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_pool.py +0 -0
  128. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/__init__.py +0 -0
  129. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/_compat.py +0 -0
  130. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/health.py +0 -0
  131. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/resilience.py +0 -0
  132. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/streaming.py +0 -0
  133. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/cli/__init__.py +0 -0
  134. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/cli/main.py +0 -0
  135. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/errors.py +0 -0
  136. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/batch.py +0 -0
  137. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/inbox.py +0 -0
  138. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/__init__.py +0 -0
  139. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/logging.py +0 -0
  140. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/otel_metrics.py +0 -0
  141. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/prometheus.py +0 -0
  142. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/observability/tracing.py +0 -0
  143. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/__init__.py +0 -0
  144. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/copy.py +0 -0
  145. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/pipeline.py +0 -0
  146. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/unnest.py +0 -0
  147. /dbkit_sql-0.1.0/tests/__init__.py → /dbkit_sql-0.3.0/src/dbkit/py.typed +0 -0
  148. {dbkit_sql-0.1.0/tests/integration → dbkit_sql-0.3.0/tests}/__init__.py +0 -0
  149. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/conftest.py +0 -0
  150. {dbkit_sql-0.1.0/tests/property → dbkit_sql-0.3.0/tests/integration}/__init__.py +0 -0
  151. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/_mp_budget_worker.py +0 -0
  152. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_cli_integration.py +0 -0
  153. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_multiprocess_connection_budget.py +0 -0
  154. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_resilience_scenarios.py +0 -0
  155. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_sharding_and_replicas.py +0 -0
  156. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/integration/test_throughput_paths.py +0 -0
  157. {dbkit_sql-0.1.0/tests/security → dbkit_sql-0.3.0/tests/property}/__init__.py +0 -0
  158. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/property/test_invariants.py +0 -0
  159. {dbkit_sql-0.1.0/tests/unit → dbkit_sql-0.3.0/tests/security}/__init__.py +0 -0
  160. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/security/test_redaction.py +0 -0
  161. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/security/test_sql_injection.py +0 -0
  162. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_benchmark_stats.py +0 -0
  163. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_bulk_batch.py +0 -0
  164. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_cancellation_shielding.py +0 -0
  165. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_circuit.py +0 -0
  166. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_dual_api.py +0 -0
  167. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_engine_registry.py +0 -0
  168. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_errors.py +0 -0
  169. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_idempotency_lint.py +0 -0
  170. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_logging.py +0 -0
  171. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_otel_metrics.py +0 -0
  172. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_policies.py +0 -0
  173. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_prometheus_metrics.py +0 -0
  174. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_query.py +0 -0
  175. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_resilience.py +0 -0
  176. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_result.py +0 -0
  177. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_sharding_replica.py +0 -0
  178. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_tracing.py +0 -0
  179. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_unasync_translation.py +0 -0
  180. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tests/unit/test_unnest.py +0 -0
  181. {dbkit_sql-0.1.0 → dbkit_sql-0.3.0}/tools/run_unasync.py +0 -0
@@ -6,6 +6,78 @@ All notable changes to this project are documented here. The format is based on
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.3.0] - 2026-07-21
10
+
11
+ ### Added
12
+ - **Transaction-scoped advisory locks** on the transaction scope (§11.7, sync mirror included):
13
+ `await tx.advisory_xact_lock(key)` (blocking, auto-released at commit/rollback — cannot leak) and
14
+ `await tx.try_advisory_xact_lock(key) -> bool` (non-blocking). `key` is an `int` (used directly)
15
+ or a `str` (hashed server-side via `hashtextextended`) — always bound, never interpolated. Waits
16
+ respect the transaction's `lock_timeout` (→ `DatabaseLockTimeoutError`). PostgreSQL only; raises
17
+ `DatabaseUnsupportedOperationError` otherwise. Serializes a read-modify-write on a logical key
18
+ without locking rows.
19
+ - **Transactional outbox** helpers in `dbkit.integrations` (the mirror of the inbox, §28.4):
20
+ `outbox_ddl` / `partitioned_outbox_ddl` / `outbox_month_partition_ddl` (schema-agnostic DDL),
21
+ `enqueue(tx, *, topic, payload, table=...)` (insert an event on the caller's transaction, atomic
22
+ with the business write), and `drain(db, *, target, publish, batch_size=..., table=...)` (relay
23
+ unsent rows with `FOR UPDATE SKIP LOCKED`, publish, mark sent — at-least-once). Single-shard;
24
+ pair with the consumer-side inbox for effectively-once. Payload is opaque JSON — no product- or
25
+ dbkit-specific columns. New examples `advisory_locks.py` + `transactional_outbox.py`.
26
+
27
+ ## [0.2.0] - 2026-07-15
28
+
29
+ ### Added
30
+ - `AsyncDatabase.ensure_database(name, config)` — idempotent registration: no-op when the
31
+ config is unchanged (lock-free, a few µs), (re)registers when missing or changed. Safe to
32
+ call in front of every query; config changes (including password-only rotations) take
33
+ effect in place with old engines disposed.
34
+ - **Dynamic-first configs**: an explicit empty ``databases: {}`` mapping is now valid —
35
+ services that discover every DSN at runtime bootstrap with no static databases. A missing
36
+ ``databases`` key is still rejected.
37
+ - **Dynamic database registration**: `AsyncDatabase.register_database(name, config)` /
38
+ `unregister_database(name)` (sync mirror included) — register shard/tenant databases whose
39
+ DSNs are discovered at runtime (e.g. from a service registry), without a service-side engine
40
+ registry. Copy-on-write config swap (readers never see a partial mapping), single-flight
41
+ registration lock, engine + limiter + breaker cleanup on replace/unregister, replica-selector
42
+ updates, and eager engine creation for `required` primaries when already started.
43
+ - `AsyncDatabase.database_scope(name, config)` — context-manager form: register for the
44
+ duration of a block (tests, migrations, one-off tenant jobs), auto-unregister + dispose on
45
+ exit. Documented anti-pattern: never scope per request — that defeats pooling; services
46
+ register long-lived shards once.
47
+ - `DatabaseConfig.from_dict(...)` — build one database config from the same dict shape as a
48
+ `databases` entry.
49
+ - `AsyncEngineRegistry.dispose_database(name)` and `ResilientExecutor.forget_database(name)`.
50
+ - `RoundRobinReplicaSelector.set_replicas(...)` / `WeightedReplicaSelector.set_replicas(...)`
51
+ for runtime replica updates.
52
+ - `dbkit.errors.OVERLOAD_CATEGORIES` / `TIMEOUT_CATEGORIES` — canonical category groupings for
53
+ HTTP mapping (503-retryable vs 504) so services stop hand-rolling exception lists.
54
+ - **`dbkit.integrations.fastapi`**: `install_exception_handlers(app)` maps `DatabaseError` by
55
+ category to RFC 7807 responses — 503 + `Retry-After` for overload, 504 for timeouts, 500 for
56
+ bugs. New optional extra: `dbkit-sql[fastapi]` (Starlette only, imported lazily).
57
+ - `py.typed` marker — mypy-strict consumers now get real types instead of `Any`.
58
+ - **`Query.settings`** — per-query, transaction-local PostgreSQL settings (e.g.
59
+ ``{"jit": "off"}``, ``{"work_mem": "64MB"}``) applied via parameterized
60
+ ``set_config(name, value, true)`` right before the statement; names validated, values bound,
61
+ never leaks past the statement's transaction.
62
+ - **`dbkit.testing`**: `FakeAsyncDatabase` / `FakeDatabase` — in-memory test doubles that
63
+ record every call (name, statement, params, target, settings, in_transaction) and return
64
+ queued rows; dynamic-registration tracking included.
65
+ - **`max_databases`** config — LRU cap on dynamically registered databases: beyond it the
66
+ least-recently-ensured dynamic database is fully purged (engines, limiter, breakers,
67
+ selector entry). Static databases are never evicted.
68
+ - `install_exception_handlers(..., database=db)` — the 503 ``Retry-After`` header now derives
69
+ from the circuit breaker's ``open_seconds`` when a facade is provided.
70
+ - Docs: new "Dynamic Registration" guide; FastAPI/`Query.settings` sections in the
71
+ integrations reference; `dbkit.testing` section in Testing & Benchmarks.
72
+
73
+ ### Fixed
74
+ - ``observability.metrics: true`` (the default) now actually wires a Prometheus sink when
75
+ ``prometheus_client`` is installed — previously the default was silently no-op. The sink is a
76
+ process-wide singleton so multiple facades share collectors safely.
77
+ - Dynamic registration now enforces the process-wide connection budget at admission time
78
+ (``connection_budget.maximum_per_process`` + ``enforce_at_startup``) — a runtime-registered
79
+ database can no longer push the process past its configured ceiling.
80
+
9
81
  ## [0.1.0] - 2026-07-15
10
82
 
11
83
  First public release on PyPI as `dbkit-sql` (import name: `dbkit`).
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dbkit-sql
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: A thin, high-throughput SQL toolkit over SQLAlchemy Core — sync and async, ORM-free.
5
5
  Project-URL: Homepage, https://github.com/talaatmagdyx/dbkit-sql
6
6
  Project-URL: Source, https://github.com/talaatmagdyx/dbkit-sql
@@ -29,6 +29,7 @@ Provides-Extra: dev
29
29
  Requires-Dist: asyncpg>=0.29; extra == 'dev'
30
30
  Requires-Dist: build>=1.2; extra == 'dev'
31
31
  Requires-Dist: docker>=7.0; extra == 'dev'
32
+ Requires-Dist: httpx2; extra == 'dev'
32
33
  Requires-Dist: hypothesis>=6.100; extra == 'dev'
33
34
  Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
34
35
  Requires-Dist: mkdocs>=1.6; extra == 'dev'
@@ -45,9 +46,13 @@ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
45
46
  Requires-Dist: pytest>=8.2; extra == 'dev'
46
47
  Requires-Dist: pyyaml>=6.0; extra == 'dev'
47
48
  Requires-Dist: ruff>=0.5; extra == 'dev'
49
+ Requires-Dist: starlette>=0.37; extra == 'dev'
50
+ Requires-Dist: starlette>=1.3.1; extra == 'dev'
48
51
  Requires-Dist: testcontainers[postgres]>=4.5; extra == 'dev'
49
52
  Requires-Dist: twine>=5.1; extra == 'dev'
50
53
  Requires-Dist: typer>=0.12; extra == 'dev'
54
+ Provides-Extra: fastapi
55
+ Requires-Dist: starlette>=0.37; extra == 'fastapi'
51
56
  Provides-Extra: orjson
52
57
  Requires-Dist: orjson>=3.10; extra == 'orjson'
53
58
  Provides-Extra: otel
@@ -390,8 +395,26 @@ target = DatabaseTarget(database="app", role="read", shard_key=f"tenant-{tenant_
390
395
  Pluggable resolvers (hash / range / directory / callable), replica routing with a
391
396
  read-your-writes override (pins reads to the primary for the scope — not lag-aware replica
392
397
  tracking), and LRU engine eviction bounded by `max_engines` so a dynamic or unbounded shard-key
393
- space still keeps a bounded number of live connections. No cross-shard transactions — pair with
394
- an outbox/saga pattern for multi-shard writes.
398
+ space still keeps a bounded number of live connections. No cross-shard transactions — for
399
+ multi-shard writes pair with a saga; for reliable event publishing on a **single** shard use the
400
+ built-in transactional outbox (`dbkit.integrations`, 0.3).
401
+
402
+ ### Dynamic registration (0.2)
403
+
404
+ Databases whose DSNs are discovered at runtime (per-tenant shards from a service registry,
405
+ rotated credentials) register on the fly — no application-side engine registry:
406
+
407
+ ```python
408
+ db = AsyncDatabase.from_config({"databases": {}, "max_databases": 500}) # dynamic-first
409
+
410
+ await db.ensure_database(shard, {"primary": {"url": dsn}}) # lock-free no-op when unchanged
411
+ rows = await db.fetch_all(query, params, target=DatabaseTarget(database=shard, role="read"))
412
+ ```
413
+
414
+ Changed configs (host moves, password rotations) re-register in place with old engines
415
+ disposed; `max_databases` LRU-evicts idle dynamic shards; registration respects the
416
+ process-wide connection budget. See the
417
+ [Dynamic Registration guide](https://talaatmagdyx.github.io/dbkit-sql/dynamic-registration/).
395
418
 
396
419
  ## Building blocks, batteries included
397
420
 
@@ -405,6 +428,8 @@ an outbox/saga pattern for multi-shard writes.
405
428
  | `unnest()` bulk strategy | Array-parameter bulk insert/upsert — ~29× a naive `execute_many` loop |
406
429
  | `db.copy_records` | PostgreSQL COPY for the largest ingest jobs |
407
430
  | Transactional inbox | Effectively-once consumer processing — dedup and business write share one transaction |
431
+ | Transactional outbox | Reliable event publishing — event row + business write share one transaction, at-least-once relay (`FOR UPDATE SKIP LOCKED`) |
432
+ | Advisory locks | Transaction-scoped `pg_advisory_xact_lock` on a logical key — serialize a read-modify-write without locking rows; auto-released at commit |
408
433
  | PgBouncer-compatible pooling | A mode for transaction-pooling PgBouncer deployments |
409
434
  | psycopg pipeline mode | A raw escape hatch for pipelined round-trips, opt-in |
410
435
  | `PrometheusMetrics` / OTel metrics & tracing | Structured observability, cost measured per adapter |
@@ -490,6 +515,8 @@ dbkit wraps `create_async_engine`/`create_engine`, so migration is incremental,
490
515
  |---|---|
491
516
  | See the smallest working consumer | [`quickstart_async.py`](examples/quickstart_async.py) · [`quickstart_sync.py`](examples/quickstart_sync.py) |
492
517
  | Use explicit transactions & savepoints | [`transactions_savepoints.py`](examples/transactions_savepoints.py) |
518
+ | Serialize work with advisory locks | [`advisory_locks.py`](examples/advisory_locks.py) |
519
+ | Publish events via the transactional outbox | [`transactional_outbox.py`](examples/transactional_outbox.py) |
493
520
  | Handle classified errors | [`error_handling.py`](examples/error_handling.py) |
494
521
  | Wire retries + the circuit breaker | [`retries_and_circuit_breaker.py`](examples/retries_and_circuit_breaker.py) |
495
522
  | Stream millions of rows | [`streaming.py`](examples/streaming.py) · [`streaming_checkpoint_resume.py`](examples/streaming_checkpoint_resume.py) |
@@ -514,7 +541,7 @@ dbkit/
514
541
  _sync/ # generated from _async/ via tools/run_unasync.py — never edited by hand
515
542
  observability/ # structured logging, Prometheus, OpenTelemetry metrics/tracing
516
543
  postgres/ # COPY, pipeline mode, unnest() bulk strategy — Postgres-only escape hatches
517
- integrations/ # transactional inbox (dedup consumer), BatchCollector micro-batching
544
+ integrations/ # transactional inbox (dedup consumer) + outbox (reliable publish), BatchCollector
518
545
  cli/ # config-validate, check, pools, engines, connection-budget, metrics
519
546
  ```
520
547
 
@@ -326,8 +326,26 @@ target = DatabaseTarget(database="app", role="read", shard_key=f"tenant-{tenant_
326
326
  Pluggable resolvers (hash / range / directory / callable), replica routing with a
327
327
  read-your-writes override (pins reads to the primary for the scope — not lag-aware replica
328
328
  tracking), and LRU engine eviction bounded by `max_engines` so a dynamic or unbounded shard-key
329
- space still keeps a bounded number of live connections. No cross-shard transactions — pair with
330
- an outbox/saga pattern for multi-shard writes.
329
+ space still keeps a bounded number of live connections. No cross-shard transactions — for
330
+ multi-shard writes pair with a saga; for reliable event publishing on a **single** shard use the
331
+ built-in transactional outbox (`dbkit.integrations`, 0.3).
332
+
333
+ ### Dynamic registration (0.2)
334
+
335
+ Databases whose DSNs are discovered at runtime (per-tenant shards from a service registry,
336
+ rotated credentials) register on the fly — no application-side engine registry:
337
+
338
+ ```python
339
+ db = AsyncDatabase.from_config({"databases": {}, "max_databases": 500}) # dynamic-first
340
+
341
+ await db.ensure_database(shard, {"primary": {"url": dsn}}) # lock-free no-op when unchanged
342
+ rows = await db.fetch_all(query, params, target=DatabaseTarget(database=shard, role="read"))
343
+ ```
344
+
345
+ Changed configs (host moves, password rotations) re-register in place with old engines
346
+ disposed; `max_databases` LRU-evicts idle dynamic shards; registration respects the
347
+ process-wide connection budget. See the
348
+ [Dynamic Registration guide](https://talaatmagdyx.github.io/dbkit-sql/dynamic-registration/).
331
349
 
332
350
  ## Building blocks, batteries included
333
351
 
@@ -341,6 +359,8 @@ an outbox/saga pattern for multi-shard writes.
341
359
  | `unnest()` bulk strategy | Array-parameter bulk insert/upsert — ~29× a naive `execute_many` loop |
342
360
  | `db.copy_records` | PostgreSQL COPY for the largest ingest jobs |
343
361
  | Transactional inbox | Effectively-once consumer processing — dedup and business write share one transaction |
362
+ | Transactional outbox | Reliable event publishing — event row + business write share one transaction, at-least-once relay (`FOR UPDATE SKIP LOCKED`) |
363
+ | Advisory locks | Transaction-scoped `pg_advisory_xact_lock` on a logical key — serialize a read-modify-write without locking rows; auto-released at commit |
344
364
  | PgBouncer-compatible pooling | A mode for transaction-pooling PgBouncer deployments |
345
365
  | psycopg pipeline mode | A raw escape hatch for pipelined round-trips, opt-in |
346
366
  | `PrometheusMetrics` / OTel metrics & tracing | Structured observability, cost measured per adapter |
@@ -426,6 +446,8 @@ dbkit wraps `create_async_engine`/`create_engine`, so migration is incremental,
426
446
  |---|---|
427
447
  | See the smallest working consumer | [`quickstart_async.py`](examples/quickstart_async.py) · [`quickstart_sync.py`](examples/quickstart_sync.py) |
428
448
  | Use explicit transactions & savepoints | [`transactions_savepoints.py`](examples/transactions_savepoints.py) |
449
+ | Serialize work with advisory locks | [`advisory_locks.py`](examples/advisory_locks.py) |
450
+ | Publish events via the transactional outbox | [`transactional_outbox.py`](examples/transactional_outbox.py) |
429
451
  | Handle classified errors | [`error_handling.py`](examples/error_handling.py) |
430
452
  | Wire retries + the circuit breaker | [`retries_and_circuit_breaker.py`](examples/retries_and_circuit_breaker.py) |
431
453
  | Stream millions of rows | [`streaming.py`](examples/streaming.py) · [`streaming_checkpoint_resume.py`](examples/streaming_checkpoint_resume.py) |
@@ -450,7 +472,7 @@ dbkit/
450
472
  _sync/ # generated from _async/ via tools/run_unasync.py — never edited by hand
451
473
  observability/ # structured logging, Prometheus, OpenTelemetry metrics/tracing
452
474
  postgres/ # COPY, pipeline mode, unnest() bulk strategy — Postgres-only escape hatches
453
- integrations/ # transactional inbox (dedup consumer), BatchCollector micro-batching
475
+ integrations/ # transactional inbox (dedup consumer) + outbox (reliable publish), BatchCollector
454
476
  cli/ # config-validate, check, pools, engines, connection-budget, metrics
455
477
  ```
456
478
 
@@ -20,6 +20,23 @@ shortcut and not notice you've silently disabled error handling for that code pa
20
20
  normal `db.execute`/`fetch_*`/`stream`/bulk methods for anything that isn't one of the two
21
21
  documented raw-driver escape hatches.
22
22
 
23
+ ## Advisory locks (transaction scope)
24
+
25
+ The scope from `db.transaction(...)` also exposes transaction-scoped PostgreSQL advisory locks —
26
+ cooperative locks on a logical key (an order id, an engagement id) rather than on rows:
27
+
28
+ ```python
29
+ async with db.transaction(target=t, lock_timeout=3.0) as tx:
30
+ await tx.advisory_xact_lock("engagement:42") # blocks until granted; auto-released at commit
31
+ ... # read-modify-write, serialized per key
32
+ ```
33
+
34
+ `await tx.advisory_xact_lock(key)` blocks until granted and holds until the transaction ends
35
+ (there is no manual unlock — it can't leak); a wait beyond the transaction's `lock_timeout` raises
36
+ `DatabaseLockTimeoutError`. `await tx.try_advisory_xact_lock(key) -> bool` is the non-blocking
37
+ variant (`False` if another transaction holds it). `key` is an `int` (used directly) or a `str`
38
+ (hashed server-side); it is always bound, never interpolated. PostgreSQL only.
39
+
23
40
  ::: dbkit.AsyncDatabase
24
41
 
25
42
  ::: dbkit.Database
@@ -0,0 +1,79 @@
1
+ # Integrations
2
+
3
+ Database-side primitives for message-driven consumers (§28) and micro-batching (§17.1).
4
+ dbkit is scoped as database-only and does not ship a broker-facing adapter — an application
5
+ wires these into its own consumer loop.
6
+
7
+ ::: dbkit.integrations.inbox_ddl
8
+
9
+ ::: dbkit.integrations.partitioned_inbox_ddl
10
+
11
+ ::: dbkit.integrations.inbox_month_partition_ddl
12
+
13
+ ::: dbkit.integrations.process_once
14
+
15
+ ::: dbkit.integrations.ack_after_commit
16
+
17
+ ## Transactional outbox (§28.4)
18
+
19
+ The mirror of the inbox: enqueue an event **in the same transaction as the business write** so the
20
+ event exists iff the change persisted, then relay unsent rows to a broker at-least-once. Single-shard
21
+ (the outbox table lives on the same database as the write); pair with the inbox on the consumer for
22
+ effectively-once. Schema-agnostic — you pass the table name and an opaque JSON payload.
23
+
24
+ ```python
25
+ from dbkit.integrations import outbox_ddl, enqueue, drain
26
+
27
+ await db.execute(sql(outbox_ddl()), target=t) # once, at setup (script: split on ';')
28
+
29
+ async with db.transaction(target=t) as tx: # atomic: write + event
30
+ await tx.execute(UPDATE_ORDER, params)
31
+ await enqueue(tx, topic="order.completed", payload={"order_id": oid})
32
+
33
+ # relay loop (separate worker): publish unsent rows, mark them sent
34
+ await drain(db, target=t, publish=my_async_publish)
35
+ ```
36
+
37
+ ::: dbkit.integrations.outbox_ddl
38
+
39
+ ::: dbkit.integrations.partitioned_outbox_ddl
40
+
41
+ ::: dbkit.integrations.outbox_month_partition_ddl
42
+
43
+ ::: dbkit.integrations.enqueue
44
+
45
+ ::: dbkit.integrations.drain
46
+
47
+ ::: dbkit.integrations.BatchCollector
48
+
49
+ ## HTTP APIs (FastAPI / Starlette)
50
+
51
+ Category-driven RFC 7807 responses for unhandled `DatabaseError`s: overload
52
+ (pool timeout, limiter, circuit open, backend unreachable) → **503** with a
53
+ `Retry-After` header (derived from the circuit breaker's `open_seconds` when you
54
+ pass your facade); query timeouts → **504**; programming/integrity errors stay
55
+ **500** and loud. Requires the `dbkit-sql[fastapi]` extra (Starlette only).
56
+
57
+ ```python
58
+ from dbkit.integrations.fastapi import install_exception_handlers
59
+
60
+ install_exception_handlers(app, database=db)
61
+ ```
62
+
63
+ ::: dbkit.integrations.fastapi.install_exception_handlers
64
+
65
+ ## Per-query session settings
66
+
67
+ `Query.settings` applies transaction-local PostgreSQL settings right before the
68
+ statement — parameterized `set_config(name, value, true)`, names validated:
69
+
70
+ ```python
71
+ COUNTS = Query(
72
+ name="inbox.counts",
73
+ statement=sql("SELECT ..."),
74
+ settings={"jit": "off"}, # or {"work_mem": "64MB"} for a heavy aggregate
75
+ )
76
+ ```
77
+
78
+ The setting never leaks: it resets when the statement's transaction ends, before
79
+ the connection returns to the pool.
@@ -0,0 +1,88 @@
1
+ # Dynamic Registration
2
+
3
+ Register databases whose DSNs are discovered at **runtime** — per-tenant shards resolved from
4
+ a service registry, credentials rotated by a secret manager — without maintaining an
5
+ application-side engine registry.
6
+
7
+ ## Bootstrap dynamic-first
8
+
9
+ An explicitly empty `databases: {}` mapping is valid; every database arrives later:
10
+
11
+ ```python
12
+ from dbkit import AsyncDatabase, DatabaseTarget, Query, sql
13
+
14
+ db = AsyncDatabase.from_config({
15
+ "databases": {}, # dynamic-first
16
+ "max_databases": 500, # LRU cap on dynamic registrations (optional)
17
+ "max_engines": 64, # LRU cap on live engines/pools (optional)
18
+ "evict_lru_engines": True,
19
+ "defaults": {
20
+ "pool": {"size": 10, "max_overflow": 0, "timeout_seconds": 2.0},
21
+ "retry": {"attempts": 2},
22
+ "circuit_breaker": {"enabled": True},
23
+ },
24
+ })
25
+ await db.start()
26
+ ```
27
+
28
+ ## `ensure_database` — the per-request pattern
29
+
30
+ Idempotent: a **lock-free no-op when the config is unchanged** (a few µs), so call it in
31
+ front of every query routed by runtime topology:
32
+
33
+ ```python
34
+ shard = my_topology.resolve(tenant_id) # -> name + DSN, however you store it
35
+
36
+ await db.ensure_database(shard.name, {
37
+ "primary": {"url": shard.dsn, "required": False},
38
+ "concurrency": {"reads": 20},
39
+ })
40
+ rows = await db.fetch_all(
41
+ LIST_ORDERS, {"tenant": tenant_id},
42
+ target=DatabaseTarget(database=shard.name, role="read"),
43
+ )
44
+ ```
45
+
46
+ A **changed** config re-registers in place: old engines are disposed (idle-only — in-flight
47
+ work finishes), and the next query connects with the new settings. This covers host moves
48
+ *and password-only rotations* with no restart.
49
+
50
+ ## Explicit control
51
+
52
+ ```python
53
+ replaced = await db.register_database("tenant-42", config) # register or replace
54
+ await db.unregister_database("tenant-42") # engines + resilience state freed
55
+
56
+ async with db.database_scope("migration-src", config) as target: # scoped lifetime
57
+ rows = await db.fetch_all(EXPORT, target=target)
58
+ # auto-unregistered — pools released even on error
59
+ ```
60
+
61
+ !!! warning "Scope `database_scope` to a unit of work, never to a request"
62
+ Engines/pools are created inside the block and disposed on exit — a per-request scope
63
+ recreates connections every request and defeats pooling. Long-lived services use
64
+ `ensure_database`/`register_database` and keep shards registered.
65
+
66
+ ## Guarantees
67
+
68
+ - **Copy-on-write config swap** — readers never observe a partially updated database map;
69
+ the query hot path takes no registration lock (~350 ns regardless of shard count).
70
+ - **Admission control** — registering past `connection_budget.maximum_per_process`
71
+ (with `enforce_at_startup: true`) raises before anything is swapped in.
72
+ - **`max_databases` LRU** — least-recently-*ensured* dynamic databases are fully purged
73
+ (engines, concurrency limiter, circuit breakers, replica-selector entry) beyond the cap.
74
+ Statically configured databases are never evicted.
75
+ - **Replicas** participate immediately: registered replicas update the built-in
76
+ round-robin/weighted selectors (custom selectors may implement `set_replicas`).
77
+
78
+ ## API reference
79
+
80
+ ::: dbkit.AsyncDatabase.ensure_database
81
+
82
+ ::: dbkit.AsyncDatabase.register_database
83
+
84
+ ::: dbkit.AsyncDatabase.unregister_database
85
+
86
+ ::: dbkit.AsyncDatabase.database_scope
87
+
88
+ ::: dbkit.DatabaseConfig.from_dict
@@ -17,9 +17,10 @@ consumers, background workers, and CLIs.
17
17
  - **Multi-database and sharded.** Named databases, pluggable shard resolvers (hash/range/
18
18
  directory/callable), replica routing with a read-your-writes override (pins reads to the
19
19
  primary for the scope, not lag-aware replica tracking), and LRU engine eviction for
20
- dynamic per-tenant deployments. No cross-shard transaction support — use an outbox/saga
21
- pattern for multi-shard writes, and note that dbkit trusts the `DatabaseTarget`/shard key
22
- you give it; tenant/shard authorization is your application's responsibility.
20
+ dynamic per-tenant deployments. No cross-shard transaction support — use a saga for atomic
21
+ multi-shard writes (a **single-shard** transactional outbox ships in `dbkit.integrations`), and
22
+ note that dbkit trusts the `DatabaseTarget`/shard key you give it; tenant/shard authorization is
23
+ your application's responsibility.
23
24
  - **Fully observable.** Structured logging, a metrics protocol (Prometheus adapter included),
24
25
  and OpenTelemetry tracing — statement text and parameters never reach a log, span, or metric
25
26
  label.
@@ -102,8 +102,9 @@ See `docs/requirements.md` for the full product/engineering requirements this ro
102
102
  the caller closes it (regression-tested). Default (`evict_lru=False`) keeps the strict
103
103
  hard-cap.
104
104
  - No cross-shard transactions — an application needing atomic multi-shard writes needs its own
105
- outbox/saga pattern; dbkit also does not authorize `DatabaseTarget`/shard-key values, so
106
- tenant/shard access control is the calling application's responsibility.
105
+ saga; dbkit ships a **single-shard** transactional outbox (`dbkit.integrations`, 0.3) but does
106
+ not coordinate distributed transactions. dbkit also does not authorize `DatabaseTarget`/shard-key
107
+ values, so tenant/shard access control is the calling application's responsibility.
107
108
  - Per-database connection budgets (`DatabaseConfig.enforce_connection_budget`): a single
108
109
  database can fail startup on its own budget, independent of the global one.
109
110
  - `AsyncEngineRegistry.dispose_one()` / `AsyncDatabase.drain_engine()` (`Database.drain_engine()`
@@ -72,4 +72,5 @@ about either warning.
72
72
 
73
73
  Each `DatabaseTarget` resolves to exactly one shard; dbkit has no distributed-transaction/2PC
74
74
  primitive. An operation that must atomically touch multiple shards needs an application-level
75
- pattern (outbox, saga) — this is a deliberate scope boundary, not a missing feature.
75
+ saga — this is a deliberate scope boundary, not a missing feature. (For reliable event publishing
76
+ within a **single** shard, dbkit does ship a transactional outbox — see `dbkit.integrations`.)
@@ -1,5 +1,35 @@
1
1
  # Testing, chaos, and benchmarks
2
2
 
3
+ ## Unit-testing consumers: `dbkit.testing`
4
+
5
+ `FakeAsyncDatabase` / `FakeDatabase` mirror the facade's query surface without a server:
6
+ queue result sets, run your code, assert on the recorded calls.
7
+
8
+ ```python
9
+ from dbkit.testing import FakeAsyncDatabase
10
+
11
+ fake = FakeAsyncDatabase()
12
+ fake.queue_rows([{"id": 1, "email": "a@x"}])
13
+
14
+ service = UserService(db=fake)
15
+ users = await service.list_users(org=7)
16
+
17
+ call = fake.calls[0]
18
+ assert call.query_name == "users.list"
19
+ assert call.params == {"org": 7}
20
+ assert call.target.database == "app"
21
+ assert not call.in_transaction
22
+ ```
23
+
24
+ Transactions yield the same fake (calls record `in_transaction=True`); dynamic
25
+ registration is tracked in `fake.registered`. `Query.settings` and the statement
26
+ text are captured per call for asserting SQL shape.
27
+
28
+ ::: dbkit.testing.FakeAsyncDatabase
29
+
30
+ ::: dbkit.testing.RecordedCall
31
+
32
+
3
33
  dbkit has five layers of verification. All commands go through `uv run` (see the `Makefile`).
4
34
 
5
35
  ## 1. Static gate (no database)
@@ -0,0 +1,42 @@
1
+ """Transaction-scoped advisory locks: serialize work on a logical key without locking rows (§11.7).
2
+
3
+ DBKIT_DSN=postgresql+psycopg://localhost/postgres python examples/advisory_locks.py
4
+
5
+ ``pg_advisory_xact_lock`` is held until the transaction ends and released automatically — the tool
6
+ for serializing a read-modify-write on a logical entity (an order, an engagement) across workers.
7
+ ``try_advisory_xact_lock`` is the non-blocking variant: skip work another worker already holds.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import os
14
+
15
+ from dbkit import AsyncDatabase, DatabaseTarget
16
+
17
+ DSN = os.environ.get("DBKIT_DSN", "postgresql+psycopg://localhost/postgres")
18
+ TARGET = DatabaseTarget(database="app", role="write")
19
+
20
+
21
+ async def main() -> None:
22
+ db = AsyncDatabase.from_config({"databases": {"app": {"primary": {"url": DSN}}}})
23
+ await db.start()
24
+ try:
25
+ # Hold the lock in one transaction; a concurrent transaction can't take the same key.
26
+ async with db.transaction(target=TARGET) as tx1:
27
+ await tx1.advisory_xact_lock("engagement:42")
28
+ async with db.transaction(target=TARGET) as tx2:
29
+ got_same = await tx2.try_advisory_xact_lock("engagement:42")
30
+ got_other = await tx2.try_advisory_xact_lock("engagement:99")
31
+ print(f"same key while held: {got_same} (expect False)")
32
+ print(f"different key: {got_other} (expect True)")
33
+ # tx1 committed -> the key is free again (xact lock auto-released).
34
+ async with db.transaction(target=TARGET) as tx3:
35
+ freed = await tx3.try_advisory_xact_lock("engagement:42")
36
+ print(f"same key after release: {freed} (expect True)")
37
+ finally:
38
+ await db.close()
39
+
40
+
41
+ if __name__ == "__main__":
42
+ asyncio.run(main())
@@ -19,6 +19,8 @@ SCRIPTS = [
19
19
  "quickstart_async.py",
20
20
  "quickstart_sync.py",
21
21
  "transactions_savepoints.py",
22
+ "advisory_locks.py",
23
+ "transactional_outbox.py",
22
24
  "error_handling.py",
23
25
  "retries_and_circuit_breaker.py",
24
26
  "streaming.py",
@@ -0,0 +1,71 @@
1
+ """Transactional outbox: enqueue an event atomically with a business write, then relay it (§28.4).
2
+
3
+ DBKIT_DSN=postgresql+psycopg://localhost/postgres python examples/transactional_outbox.py
4
+
5
+ The event row and the business write commit together, so the event exists iff the change
6
+ persisted. A separate relay reads unsent rows and publishes them (here, just prints), marking each
7
+ sent. Delivery is at-least-once — pair with the consumer-side inbox for effectively-once.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import os
14
+
15
+ from dbkit import AsyncDatabase, DatabaseTarget, sql
16
+ from dbkit.integrations import drain, enqueue, outbox_ddl
17
+
18
+ DSN = os.environ.get("DBKIT_DSN", "postgresql+psycopg://localhost/postgres")
19
+ TARGET = DatabaseTarget(database="app", role="write")
20
+ OUTBOX = "dbkit_example_outbox"
21
+
22
+
23
+ async def main() -> None:
24
+ db = AsyncDatabase.from_config({"databases": {"app": {"primary": {"url": DSN}}}})
25
+ await db.start()
26
+ try:
27
+ for stmt in outbox_ddl(OUTBOX).split(";"):
28
+ if stmt.strip():
29
+ await db.execute(sql(stmt), target=TARGET)
30
+ await db.execute(sql(f"TRUNCATE {OUTBOX}"), target=TARGET)
31
+ await db.execute(
32
+ sql("CREATE TABLE IF NOT EXISTS dbkit_example_orders (order_id text PRIMARY KEY)"),
33
+ target=TARGET,
34
+ )
35
+ await db.execute(sql("TRUNCATE dbkit_example_orders"), target=TARGET)
36
+
37
+ # 1. Business write + event, one atomic transaction.
38
+ async with db.transaction(target=TARGET) as tx:
39
+ await tx.execute(
40
+ sql("INSERT INTO dbkit_example_orders (order_id) VALUES (:o)"), {"o": "order-42"}
41
+ )
42
+ await enqueue(
43
+ tx, topic="order.completed", payload={"order_id": "order-42"}, table=OUTBOX
44
+ )
45
+
46
+ # 2. A failed business write takes its event down with it (atomicity).
47
+ try:
48
+ async with db.transaction(target=TARGET) as tx:
49
+ await enqueue(
50
+ tx, topic="order.completed", payload={"order_id": "ghost"}, table=OUTBOX
51
+ )
52
+ raise RuntimeError("business failure")
53
+ except RuntimeError:
54
+ pass
55
+ pending = await db.fetch_value(sql(f"SELECT count(*) FROM {OUTBOX}"), target=TARGET)
56
+ print(f"pending events after 1 commit + 1 rollback: {pending} (expect 1)")
57
+
58
+ # 3. Relay: publish unsent rows, mark them sent.
59
+ async def publish(row: dict) -> None:
60
+ print(f" -> publish topic={row['topic']} payload={row['payload']}")
61
+
62
+ relayed = await drain(db, target=TARGET, publish=publish, table=OUTBOX)
63
+ print(f"relayed: {relayed} (expect 1)")
64
+ again = await drain(db, target=TARGET, publish=publish, table=OUTBOX)
65
+ print(f"second drain: {again} (expect 0)")
66
+ finally:
67
+ await db.close()
68
+
69
+
70
+ if __name__ == "__main__":
71
+ asyncio.run(main())
@@ -9,6 +9,7 @@ docs_dir: docs
9
9
 
10
10
  nav:
11
11
  - Home: index.md
12
+ - Dynamic Registration: dynamic-registration.md
12
13
  - CLI: cli.md
13
14
  - API Reference:
14
15
  - Database (async/sync): api/database.md
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dbkit-sql"
7
- version = "0.1.0"
7
+ version = "0.3.0"
8
8
  description = "A thin, high-throughput SQL toolkit over SQLAlchemy Core — sync and async, ORM-free."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -37,8 +37,14 @@ pydantic = ["pydantic>=2.7"]
37
37
  orjson = ["orjson>=3.10"]
38
38
  cli = ["typer>=0.12"]
39
39
  bench = ["psutil>=5.9"]
40
+ # RFC 7807 exception handlers for FastAPI/Starlette apps (dbkit.integrations.fastapi)
41
+ fastapi = ["starlette>=0.37"]
40
42
  dev = [
41
- "dbkit-sql[psycopg,asyncpg,yaml,prometheus,pydantic,bench,otel,cli]",
43
+ "dbkit-sql[psycopg,asyncpg,yaml,prometheus,pydantic,bench,otel,cli,fastapi]",
44
+ # starlette 1.x TestClient requires httpx2 (0.x used httpx). Keep dev on a
45
+ # current, CVE-free starlette; the runtime [fastapi] extra stays permissive.
46
+ "starlette>=1.3.1",
47
+ "httpx2",
42
48
  "pytest>=8.2",
43
49
  "pytest-asyncio>=0.23",
44
50
  "pytest-cov>=5.0",
@@ -40,7 +40,7 @@ from ._core.routing import (
40
40
  )
41
41
  from ._sync.database import Database
42
42
 
43
- __version__ = "0.1.0"
43
+ __version__ = "0.3.0"
44
44
 
45
45
  __all__ = [
46
46
  "AsyncDatabase",