dbkit-sql 0.2.0__tar.gz → 0.3.1__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 (183) hide show
  1. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/CHANGELOG.md +45 -0
  2. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/PKG-INFO +10 -5
  3. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/README.md +8 -3
  4. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/database.md +17 -0
  5. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/integrations.md +30 -0
  6. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/index.md +4 -3
  7. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/roadmap.md +3 -2
  8. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/security.md +2 -1
  9. dbkit_sql-0.3.1/examples/advisory_locks.py +42 -0
  10. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/run_all.py +2 -0
  11. dbkit_sql-0.3.1/examples/transactional_outbox.py +71 -0
  12. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/pyproject.toml +1 -1
  13. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/__init__.py +1 -1
  14. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/_compat.py +26 -0
  15. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/engine.py +5 -3
  16. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/executor.py +8 -1
  17. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/transaction.py +60 -3
  18. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/config.py +7 -0
  19. dbkit_sql-0.3.1/src/dbkit/_core/errors/redaction.py +151 -0
  20. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/_compat.py +15 -0
  21. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/engine.py +5 -3
  22. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/executor.py +8 -1
  23. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/transaction.py +60 -3
  24. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/integrations/__init__.py +12 -0
  25. dbkit_sql-0.3.1/src/dbkit/integrations/outbox.py +158 -0
  26. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_async_integration.py +90 -0
  27. dbkit_sql-0.3.1/tests/integration/test_commit_interruption.py +74 -0
  28. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_sync_integration.py +11 -0
  29. dbkit_sql-0.3.1/tests/security/test_redaction.py +301 -0
  30. dbkit_sql-0.3.1/tests/unit/test_commit_cancellation.py +351 -0
  31. dbkit_sql-0.3.1/tests/unit/test_integrations_outbox.py +70 -0
  32. dbkit_sql-0.2.0/src/dbkit/_core/errors/redaction.py +0 -96
  33. dbkit_sql-0.2.0/tests/security/test_redaction.py +0 -85
  34. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
  35. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  36. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
  37. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  38. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/dependabot.yml +0 -0
  39. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/workflows/ci.yml +0 -0
  40. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/workflows/dependency-matrix.yml +0 -0
  41. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/workflows/docs.yml +0 -0
  42. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/workflows/release.yml +0 -0
  43. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.github/workflows/security.yml +0 -0
  44. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/.gitignore +0 -0
  45. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/CONTRIBUTING.md +0 -0
  46. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/LICENSE +0 -0
  47. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/Makefile +0 -0
  48. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/SECURITY.md +0 -0
  49. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/__init__.py +0 -0
  50. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/__main__.py +0 -0
  51. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/_common.py +0 -0
  52. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/_results.py +0 -0
  53. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/_stats.py +0 -0
  54. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_batch.py +0 -0
  55. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_batch_collector.py +0 -0
  56. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_concurrency_scaling.py +0 -0
  57. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_crud.py +0 -0
  58. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_latency.py +0 -0
  59. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_observability_overhead.py +0 -0
  60. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_overhead.py +0 -0
  61. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_pgbouncer_compatible.py +0 -0
  62. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_pool_exhaustion.py +0 -0
  63. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_shard_cardinality.py +0 -0
  64. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_streaming_scale.py +0 -0
  65. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_throughput.py +0 -0
  66. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/bench_unnest.py +0 -0
  67. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/check_regression.py +0 -0
  68. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/benchmarks/soak.py +0 -0
  69. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docker-compose.yml +0 -0
  70. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/config.md +0 -0
  71. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/errors.md +0 -0
  72. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/observability.md +0 -0
  73. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/api/query.md +0 -0
  74. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/assets/logo.svg +0 -0
  75. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/cli.md +0 -0
  76. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/dynamic-registration.md +0 -0
  77. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/observability.md +0 -0
  78. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/requirements.md +0 -0
  79. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/testing.md +0 -0
  80. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/troubleshooting.md +0 -0
  81. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/docs/versioning.md +0 -0
  82. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/batch_collector.py +0 -0
  83. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/bulk_insert_upsert.py +0 -0
  84. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/copy_ingest.py +0 -0
  85. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/error_handling.py +0 -0
  86. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/health_and_pool.py +0 -0
  87. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/inbox_idempotent_consumer.py +0 -0
  88. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/opentelemetry_observability.py +0 -0
  89. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/pgbouncer_mode.py +0 -0
  90. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/pipeline_mode.py +0 -0
  91. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/quickstart_async.py +0 -0
  92. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/quickstart_sync.py +0 -0
  93. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/retries_and_circuit_breaker.py +0 -0
  94. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/streaming.py +0 -0
  95. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/streaming_checkpoint_resume.py +0 -0
  96. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/sync_feature_parity.py +0 -0
  97. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/examples/transactions_savepoints.py +0 -0
  98. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/mkdocs.yml +0 -0
  99. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/__init__.py +0 -0
  100. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/connection.py +0 -0
  101. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/database.py +0 -0
  102. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/health.py +0 -0
  103. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/resilience.py +0 -0
  104. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_async/streaming.py +0 -0
  105. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/__init__.py +0 -0
  106. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/bulk.py +0 -0
  107. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/circuit.py +0 -0
  108. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/errors/__init__.py +0 -0
  109. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/errors/base.py +0 -0
  110. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/errors/classifier.py +0 -0
  111. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/errors/sqlstate.py +0 -0
  112. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/idempotency_lint.py +0 -0
  113. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/keys.py +0 -0
  114. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/policies.py +0 -0
  115. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/query.py +0 -0
  116. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/result.py +0 -0
  117. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_core/routing.py +0 -0
  118. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_pool.py +0 -0
  119. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/__init__.py +0 -0
  120. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/connection.py +0 -0
  121. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/database.py +0 -0
  122. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/health.py +0 -0
  123. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/resilience.py +0 -0
  124. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/_sync/streaming.py +0 -0
  125. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/cli/__init__.py +0 -0
  126. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/cli/main.py +0 -0
  127. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/errors.py +0 -0
  128. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/integrations/batch.py +0 -0
  129. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/integrations/fastapi.py +0 -0
  130. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/integrations/inbox.py +0 -0
  131. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/__init__.py +0 -0
  132. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/logging.py +0 -0
  133. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/metrics.py +0 -0
  134. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/otel_metrics.py +0 -0
  135. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/prometheus.py +0 -0
  136. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/observability/tracing.py +0 -0
  137. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/postgres/__init__.py +0 -0
  138. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/postgres/copy.py +0 -0
  139. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/postgres/pipeline.py +0 -0
  140. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/postgres/unnest.py +0 -0
  141. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/py.typed +0 -0
  142. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/src/dbkit/testing/__init__.py +0 -0
  143. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/__init__.py +0 -0
  144. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/conftest.py +0 -0
  145. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/__init__.py +0 -0
  146. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/_mp_budget_worker.py +0 -0
  147. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_cli_integration.py +0 -0
  148. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_multiprocess_connection_budget.py +0 -0
  149. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_resilience_scenarios.py +0 -0
  150. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_sharding_and_replicas.py +0 -0
  151. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/integration/test_throughput_paths.py +0 -0
  152. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/property/__init__.py +0 -0
  153. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/property/test_invariants.py +0 -0
  154. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/security/__init__.py +0 -0
  155. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/security/test_sql_injection.py +0 -0
  156. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/__init__.py +0 -0
  157. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_benchmark_stats.py +0 -0
  158. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_bulk_batch.py +0 -0
  159. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_cancellation_shielding.py +0 -0
  160. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_circuit.py +0 -0
  161. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_cli.py +0 -0
  162. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_config.py +0 -0
  163. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_default_metrics_sink.py +0 -0
  164. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_dual_api.py +0 -0
  165. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_dynamic_registration.py +0 -0
  166. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_engine_registry.py +0 -0
  167. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_errors.py +0 -0
  168. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_fastapi_integration.py +0 -0
  169. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_idempotency_lint.py +0 -0
  170. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_logging.py +0 -0
  171. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_otel_metrics.py +0 -0
  172. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_policies.py +0 -0
  173. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_prometheus_metrics.py +0 -0
  174. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_query.py +0 -0
  175. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_query_settings.py +0 -0
  176. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_resilience.py +0 -0
  177. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_result.py +0 -0
  178. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_sharding_replica.py +0 -0
  179. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_testing_fakes.py +0 -0
  180. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_tracing.py +0 -0
  181. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_unasync_translation.py +0 -0
  182. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tests/unit/test_unnest.py +0 -0
  183. {dbkit_sql-0.2.0 → dbkit_sql-0.3.1}/tools/run_unasync.py +0 -0
@@ -6,6 +6,51 @@ All notable changes to this project are documented here. The format is based on
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.3.1] - 2026-11-21
10
+
11
+ ### Security
12
+ - **DSN passwords are redacted in every form** wherever a URL or driver message can reach a log, trace, metric
13
+ or error (§30): URL userinfo (including passwords containing `/`, `+`, `=` or spaces, the password-only
14
+ `scheme://:pw@host` form and percent-encoded passwords), URL query parameters whose decoded key contains
15
+ `password` (`?password=`, `?sslpassword=`, `?db_password=`, nested `?next=/x?password=`), libpq keyword DSNs
16
+ and other `password`-like keys (`password=`, `PGPASSWORD=`, `db_password: x`, quoted or not), and mapping or
17
+ JSON forms (`'password': 'x'`, `"password":"x"`). A value after a recognised key is redacted to its natural
18
+ end, so an unusual or very long value is hidden whole. `TargetConfig.__repr__` (and so the reprs of
19
+ `DatabaseConfig` and `DbkitConfig`) uses the same redaction; the URL itself is unchanged for the engine.
20
+ - **Redaction time is bounded** on long, attacker-influenced error text: search patterns are bounded and anchored,
21
+ and `sanitize_message` cuts messages to 8192 characters before redacting (a DSN password cut before its `@` is
22
+ redacted to the end), so no text past the cut reaches the output.
23
+ - **Engine-creation errors keep no driver error in their chain.** The error is raised outside the `except` block,
24
+ so a driver message that echoes the URL is not kept as `__context__` (sync and async).
25
+
26
+ ### Fixed
27
+ - **An interruption during COMMIT is never swallowed or reclassified** (task cancellation, `KeyboardInterrupt`,
28
+ `SystemExit`; §15): no rollback is attempted, the connection is invalidated inside a shield and never reused,
29
+ the outcome is counted as `commit_unknown`, and the interruption propagates unchanged. This covers explicit
30
+ transactions and the auto-commit scope behind `execute`, `execute_many`, `connection()` and best-effort bulk,
31
+ sync and async. A further cancellation or a failure while invalidating is added as a note on the original
32
+ exception (saying whether the invalidate finished); a `KeyboardInterrupt` or `SystemExit` raised while
33
+ invalidating outranks the original and propagates.
34
+ - A password-less URL followed by an unrelated `@` later in a message stays readable (`host:port/db`).
35
+
36
+ ## [0.3.0] - 2026-07-21
37
+
38
+ ### Added
39
+ - **Transaction-scoped advisory locks** on the transaction scope (§11.7, sync mirror included):
40
+ `await tx.advisory_xact_lock(key)` (blocking, auto-released at commit/rollback — cannot leak) and
41
+ `await tx.try_advisory_xact_lock(key) -> bool` (non-blocking). `key` is an `int` (used directly)
42
+ or a `str` (hashed server-side via `hashtextextended`) — always bound, never interpolated. Waits
43
+ respect the transaction's `lock_timeout` (→ `DatabaseLockTimeoutError`). PostgreSQL only; raises
44
+ `DatabaseUnsupportedOperationError` otherwise. Serializes a read-modify-write on a logical key
45
+ without locking rows.
46
+ - **Transactional outbox** helpers in `dbkit.integrations` (the mirror of the inbox, §28.4):
47
+ `outbox_ddl` / `partitioned_outbox_ddl` / `outbox_month_partition_ddl` (schema-agnostic DDL),
48
+ `enqueue(tx, *, topic, payload, table=...)` (insert an event on the caller's transaction, atomic
49
+ with the business write), and `drain(db, *, target, publish, batch_size=..., table=...)` (relay
50
+ unsent rows with `FOR UPDATE SKIP LOCKED`, publish, mark sent — at-least-once). Single-shard;
51
+ pair with the consumer-side inbox for effectively-once. Payload is opaque JSON — no product- or
52
+ dbkit-specific columns. New examples `advisory_locks.py` + `transactional_outbox.py`.
53
+
9
54
  ## [0.2.0] - 2026-07-15
10
55
 
11
56
  ### Added
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: dbkit-sql
3
- Version: 0.2.0
3
+ Version: 0.3.1
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
@@ -395,8 +395,9 @@ target = DatabaseTarget(database="app", role="read", shard_key=f"tenant-{tenant_
395
395
  Pluggable resolvers (hash / range / directory / callable), replica routing with a
396
396
  read-your-writes override (pins reads to the primary for the scope — not lag-aware replica
397
397
  tracking), and LRU engine eviction bounded by `max_engines` so a dynamic or unbounded shard-key
398
- space still keeps a bounded number of live connections. No cross-shard transactions — pair with
399
- 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).
400
401
 
401
402
  ### Dynamic registration (0.2)
402
403
 
@@ -427,6 +428,8 @@ process-wide connection budget. See the
427
428
  | `unnest()` bulk strategy | Array-parameter bulk insert/upsert — ~29× a naive `execute_many` loop |
428
429
  | `db.copy_records` | PostgreSQL COPY for the largest ingest jobs |
429
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 |
430
433
  | PgBouncer-compatible pooling | A mode for transaction-pooling PgBouncer deployments |
431
434
  | psycopg pipeline mode | A raw escape hatch for pipelined round-trips, opt-in |
432
435
  | `PrometheusMetrics` / OTel metrics & tracing | Structured observability, cost measured per adapter |
@@ -512,6 +515,8 @@ dbkit wraps `create_async_engine`/`create_engine`, so migration is incremental,
512
515
  |---|---|
513
516
  | See the smallest working consumer | [`quickstart_async.py`](examples/quickstart_async.py) · [`quickstart_sync.py`](examples/quickstart_sync.py) |
514
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) |
515
520
  | Handle classified errors | [`error_handling.py`](examples/error_handling.py) |
516
521
  | Wire retries + the circuit breaker | [`retries_and_circuit_breaker.py`](examples/retries_and_circuit_breaker.py) |
517
522
  | Stream millions of rows | [`streaming.py`](examples/streaming.py) · [`streaming_checkpoint_resume.py`](examples/streaming_checkpoint_resume.py) |
@@ -536,7 +541,7 @@ dbkit/
536
541
  _sync/ # generated from _async/ via tools/run_unasync.py — never edited by hand
537
542
  observability/ # structured logging, Prometheus, OpenTelemetry metrics/tracing
538
543
  postgres/ # COPY, pipeline mode, unnest() bulk strategy — Postgres-only escape hatches
539
- integrations/ # transactional inbox (dedup consumer), BatchCollector micro-batching
544
+ integrations/ # transactional inbox (dedup consumer) + outbox (reliable publish), BatchCollector
540
545
  cli/ # config-validate, check, pools, engines, connection-budget, metrics
541
546
  ```
542
547
 
@@ -326,8 +326,9 @@ 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).
331
332
 
332
333
  ### Dynamic registration (0.2)
333
334
 
@@ -358,6 +359,8 @@ process-wide connection budget. See the
358
359
  | `unnest()` bulk strategy | Array-parameter bulk insert/upsert — ~29× a naive `execute_many` loop |
359
360
  | `db.copy_records` | PostgreSQL COPY for the largest ingest jobs |
360
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 |
361
364
  | PgBouncer-compatible pooling | A mode for transaction-pooling PgBouncer deployments |
362
365
  | psycopg pipeline mode | A raw escape hatch for pipelined round-trips, opt-in |
363
366
  | `PrometheusMetrics` / OTel metrics & tracing | Structured observability, cost measured per adapter |
@@ -443,6 +446,8 @@ dbkit wraps `create_async_engine`/`create_engine`, so migration is incremental,
443
446
  |---|---|
444
447
  | See the smallest working consumer | [`quickstart_async.py`](examples/quickstart_async.py) · [`quickstart_sync.py`](examples/quickstart_sync.py) |
445
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) |
446
451
  | Handle classified errors | [`error_handling.py`](examples/error_handling.py) |
447
452
  | Wire retries + the circuit breaker | [`retries_and_circuit_breaker.py`](examples/retries_and_circuit_breaker.py) |
448
453
  | Stream millions of rows | [`streaming.py`](examples/streaming.py) · [`streaming_checkpoint_resume.py`](examples/streaming_checkpoint_resume.py) |
@@ -467,7 +472,7 @@ dbkit/
467
472
  _sync/ # generated from _async/ via tools/run_unasync.py — never edited by hand
468
473
  observability/ # structured logging, Prometheus, OpenTelemetry metrics/tracing
469
474
  postgres/ # COPY, pipeline mode, unnest() bulk strategy — Postgres-only escape hatches
470
- integrations/ # transactional inbox (dedup consumer), BatchCollector micro-batching
475
+ integrations/ # transactional inbox (dedup consumer) + outbox (reliable publish), BatchCollector
471
476
  cli/ # config-validate, check, pools, engines, connection-budget, metrics
472
477
  ```
473
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
@@ -14,6 +14,36 @@ wires these into its own consumer loop.
14
14
 
15
15
  ::: dbkit.integrations.ack_after_commit
16
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
+
17
47
  ::: dbkit.integrations.BatchCollector
18
48
 
19
49
  ## HTTP APIs (FastAPI / Starlette)
@@ -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`.)
@@ -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())
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dbkit-sql"
7
- version = "0.2.0"
7
+ version = "0.3.1"
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"
@@ -40,7 +40,7 @@ from ._core.routing import (
40
40
  )
41
41
  from ._sync.database import Database
42
42
 
43
- __version__ = "0.2.0"
43
+ __version__ = "0.3.1"
44
44
 
45
45
  __all__ = [
46
46
  "AsyncDatabase",
@@ -109,3 +109,29 @@ async def shield_from_cancellation(coro: Coroutine[Any, Any, T]) -> T:
109
109
  with contextlib.suppress(asyncio.CancelledError, Exception):
110
110
  await asyncio.shield(task)
111
111
  raise
112
+
113
+
114
+ async def invalidate_after_interrupted_commit(conn: Any, original: BaseException) -> None:
115
+ """Drop a connection whose COMMIT was interrupted (outcome unknown) from the pool, shielded.
116
+
117
+ A failure or a further cancellation while invalidating is noted on ``original`` (which the
118
+ caller re-raises), saying whether the invalidate finished, so it is never silently lost. (A
119
+ KeyboardInterrupt or SystemExit raised inside the shielded invalidate escapes through the event
120
+ loop, as asyncio does for those, rather than reaching this coroutine.)"""
121
+ finished = False
122
+
123
+ async def _invalidate() -> None:
124
+ nonlocal finished
125
+ await conn.invalidate()
126
+ finished = True
127
+
128
+ try:
129
+ await shield_from_cancellation(_invalidate())
130
+ except BaseException as second:
131
+ if not (isinstance(second, Exception) or is_cancellation(second)):
132
+ raise
133
+ state = "finished" if finished else "did not finish"
134
+ original.add_note(
135
+ f"dbkit: {type(second).__name__} while invalidating the connection; "
136
+ f"the invalidate {state}"
137
+ )
@@ -18,6 +18,7 @@ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
18
18
 
19
19
  from .._core.config import DbkitConfig, PoolConfig, TargetConfig
20
20
  from .._core.errors import DatabaseConfigurationError, DatabaseRoutingError
21
+ from .._core.errors.redaction import sanitize_message
21
22
  from .._core.keys import EngineKey
22
23
  from .._core.routing import ResolvedRoute
23
24
  from .._pool import PoolInstrumentation, PoolSnapshot
@@ -136,9 +137,10 @@ class AsyncEngineRegistry:
136
137
  try:
137
138
  return create_async_engine(target.url, **kwargs)
138
139
  except Exception as exc:
139
- raise DatabaseConfigurationError(
140
- f"failed to create engine for {target.name!r}: {exc}"
141
- ) from exc
140
+ reason = sanitize_message(str(exc))
141
+ # Raised outside the except block, so the driver error (which can echo the URL, password
142
+ # included) is not even kept as __context__ (§30).
143
+ raise DatabaseConfigurationError(f"failed to create engine for {target.name!r}: {reason}")
142
144
 
143
145
  async def get(self, route: ResolvedRoute) -> EngineEntry:
144
146
  """The cached engine for ``route``, creating (and, if needed, evicting) one lazily."""
@@ -34,7 +34,7 @@ from ..observability import logging as obslog
34
34
  from ..observability import metrics as m
35
35
  from ..observability.metrics import MetricsSink
36
36
  from ..observability.tracing import Tracer
37
- from ._compat import API_LABEL
37
+ from ._compat import API_LABEL, invalidate_after_interrupted_commit
38
38
  from .connection import AsyncConnectionScope
39
39
  from .engine import AsyncEngineRegistry, EngineEntry
40
40
  from .resilience import ConcurrencyLimiter, run_with_retries
@@ -283,6 +283,13 @@ class ResilientExecutor:
283
283
  try:
284
284
  await conn.commit()
285
285
  except BaseException as commit_exc:
286
+ if not isinstance(commit_exc, Exception):
287
+ # Interrupted during COMMIT (cancellation, KeyboardInterrupt,
288
+ # SystemExit): the outcome is unknown. No rollback; the connection is
289
+ # invalidated, never reused; the interruption propagates unchanged.
290
+ self._metrics.incr(m.COMMIT_UNKNOWN, labels=labels) # counted first
291
+ await invalidate_after_interrupted_commit(conn, commit_exc)
292
+ raise commit_exc
286
293
  # Mirror _AsyncTransactionManager._commit(): a failure during COMMIT
287
294
  # may mean the write committed anyway (§15) — never silently swallow
288
295
  # that ambiguity, and never leave the exception unclassified either
@@ -18,13 +18,14 @@ from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
18
18
 
19
19
  from .._core.errors import (
20
20
  DatabaseCommitUnknownError,
21
+ DatabaseUnsupportedOperationError,
21
22
  classify,
22
23
  is_connection_error,
23
24
  )
24
25
  from ..observability import logging as obslog
25
26
  from ..observability import metrics as m
26
27
  from ..observability.metrics import MetricsSink, NoopMetrics
27
- from ._compat import is_cancellation, shield_from_cancellation
28
+ from ._compat import invalidate_after_interrupted_commit, is_cancellation, shield_from_cancellation
28
29
  from .connection import AsyncConnectionScope, apply_statement_timeout_sql
29
30
 
30
31
 
@@ -63,6 +64,53 @@ class AsyncTransactionScope(AsyncConnectionScope):
63
64
  else:
64
65
  await nested.commit()
65
66
 
67
+ async def advisory_xact_lock(self, key: int | str) -> None:
68
+ """Acquire a transaction-scoped PostgreSQL advisory lock, blocking until granted (§11.7).
69
+
70
+ The lock is held for the remainder of THIS transaction and released automatically on
71
+ ``COMMIT``/``ROLLBACK`` — there is no manual unlock, so it can never leak. It serializes
72
+ transactions that lock the same ``key``: a second locker of the same key blocks until the
73
+ first transaction ends. Nothing else is blocked (advisory locks are cooperative — they only
74
+ guard code paths that agree to take the same lock), so it is the tool for serializing a
75
+ read-modify-write on a logical entity without locking its rows.
76
+
77
+ ``key`` is either a 64-bit ``int`` (used directly as the lock key) or a ``str`` (hashed to a
78
+ ``bigint`` server-side via ``hashtextextended(key, 0)``). It is always passed as a bound
79
+ parameter — never string-interpolated.
80
+
81
+ The wait respects the transaction's ``lock_timeout`` (set via
82
+ :meth:`~dbkit.AsyncDatabase.transaction`'s ``lock_timeout=`` argument): a wait that exceeds
83
+ it raises :class:`~dbkit.errors.DatabaseLockTimeoutError` (retryable). PostgreSQL only;
84
+ raises :class:`~dbkit.errors.DatabaseUnsupportedOperationError` otherwise.
85
+ """
86
+ await self._advisory_lock("pg_advisory_xact_lock", key, name="advisory_xact_lock")
87
+
88
+ async def try_advisory_xact_lock(self, key: int | str) -> bool:
89
+ """Try to take a transaction-scoped advisory lock without blocking (§11.7).
90
+
91
+ Returns ``True`` if the lock was granted (held until this transaction ends), ``False`` if
92
+ another transaction already holds it. Never waits, so ``lock_timeout`` does not apply — use
93
+ this to fail fast (e.g. skip work another worker is already doing) instead of queuing.
94
+ ``key`` and dialect rules match :meth:`advisory_xact_lock`.
95
+ """
96
+ result = await self._advisory_lock(
97
+ "pg_try_advisory_xact_lock", key, name="try_advisory_xact_lock"
98
+ )
99
+ return bool(result)
100
+
101
+ async def _advisory_lock(self, func: str, key: int | str, *, name: str) -> Any:
102
+ """Run one advisory-lock function (``func`` is an internal literal, ``key`` is bound)."""
103
+ if not self._is_postgres:
104
+ raise DatabaseUnsupportedOperationError("advisory locks require PostgreSQL")
105
+ arg = "hashtextextended(:key, 0)" if isinstance(key, str) else ":key"
106
+ try:
107
+ cursor = await self._conn.execute(text(f"SELECT {func}({arg})"), {"key": key})
108
+ return cursor.scalar()
109
+ except Exception as exc:
110
+ raise classify(
111
+ exc, query_name=name, database_name=self._database, role=self._role
112
+ ) from exc
113
+
66
114
 
67
115
  class _AsyncTransactionManager:
68
116
  """Async context manager implementing the transaction lifecycle (§11.1, §11.3)."""
@@ -178,8 +226,10 @@ class _AsyncTransactionManager:
178
226
  except DatabaseCommitUnknownError:
179
227
  outcome = "commit_unknown"
180
228
  raise
181
- except BaseException:
182
- outcome = "rollback" # _commit() already attempted an internal rollback
229
+ except BaseException as commit_exc:
230
+ # Interrupted during COMMIT: the outcome is not known. Otherwise _commit() already
231
+ # attempted an internal rollback.
232
+ outcome = "rollback" if isinstance(commit_exc, Exception) else "commit_unknown"
183
233
  raise
184
234
  return False
185
235
  finally:
@@ -207,6 +257,13 @@ class _AsyncTransactionManager:
207
257
  try:
208
258
  await self._trans.commit()
209
259
  except BaseException as commit_exc:
260
+ if not isinstance(commit_exc, Exception):
261
+ # Interrupted (task cancellation, KeyboardInterrupt, SystemExit) during COMMIT:
262
+ # it may or may not have landed. A rollback would prove nothing; the connection's
263
+ # state is unknown, so it is invalidated (never reused), then the interruption
264
+ # propagates unchanged.
265
+ await invalidate_after_interrupted_commit(self._conn, commit_exc)
266
+ raise commit_exc
210
267
  # A failure during COMMIT may mean the transaction committed anyway (§15).
211
268
  if is_connection_error(commit_exc):
212
269
  raise DatabaseCommitUnknownError(
@@ -215,6 +215,13 @@ class TargetConfig:
215
215
  weight: int = 1
216
216
  pool: PoolConfig | None = None # falls back to defaults.pool
217
217
 
218
+ def __repr__(self) -> str:
219
+ # The URL may carry a password; reprs reach logs, tracebacks and reporters (§30).
220
+ return (
221
+ f"TargetConfig(url={redact_dsn(self.url)!r}, name={self.name!r}, "
222
+ f"required={self.required!r}, weight={self.weight!r}, pool={self.pool!r})"
223
+ )
224
+
218
225
  def resolved_pool(self, defaults: Defaults) -> PoolConfig:
219
226
  """This target's own pool config, or ``defaults.pool`` if it doesn't override one."""
220
227
  return self.pool or defaults.pool