dbkit-sql 0.2.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 (179) hide show
  1. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/CHANGELOG.md +18 -0
  2. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/PKG-INFO +9 -4
  3. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/README.md +8 -3
  4. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/database.md +17 -0
  5. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/integrations.md +30 -0
  6. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/index.md +4 -3
  7. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/roadmap.md +3 -2
  8. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/security.md +2 -1
  9. dbkit_sql-0.3.0/examples/advisory_locks.py +42 -0
  10. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/run_all.py +2 -0
  11. dbkit_sql-0.3.0/examples/transactional_outbox.py +71 -0
  12. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/pyproject.toml +1 -1
  13. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/__init__.py +1 -1
  14. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/transaction.py +48 -0
  15. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/transaction.py +48 -0
  16. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/__init__.py +12 -0
  17. dbkit_sql-0.3.0/src/dbkit/integrations/outbox.py +158 -0
  18. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_async_integration.py +90 -0
  19. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_sync_integration.py +11 -0
  20. dbkit_sql-0.3.0/tests/unit/test_integrations_outbox.py +70 -0
  21. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
  22. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  23. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
  24. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  25. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/dependabot.yml +0 -0
  26. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/ci.yml +0 -0
  27. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/dependency-matrix.yml +0 -0
  28. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/docs.yml +0 -0
  29. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/release.yml +0 -0
  30. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/security.yml +0 -0
  31. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.gitignore +0 -0
  32. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/CONTRIBUTING.md +0 -0
  33. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/LICENSE +0 -0
  34. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/Makefile +0 -0
  35. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/SECURITY.md +0 -0
  36. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/__init__.py +0 -0
  37. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/__main__.py +0 -0
  38. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_common.py +0 -0
  39. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_results.py +0 -0
  40. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_stats.py +0 -0
  41. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch.py +0 -0
  42. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch_collector.py +0 -0
  43. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_concurrency_scaling.py +0 -0
  44. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_crud.py +0 -0
  45. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_latency.py +0 -0
  46. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_observability_overhead.py +0 -0
  47. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_overhead.py +0 -0
  48. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_pgbouncer_compatible.py +0 -0
  49. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_pool_exhaustion.py +0 -0
  50. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_shard_cardinality.py +0 -0
  51. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_streaming_scale.py +0 -0
  52. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_throughput.py +0 -0
  53. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_unnest.py +0 -0
  54. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/check_regression.py +0 -0
  55. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/soak.py +0 -0
  56. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docker-compose.yml +0 -0
  57. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/config.md +0 -0
  58. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/errors.md +0 -0
  59. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/observability.md +0 -0
  60. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/query.md +0 -0
  61. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/assets/logo.svg +0 -0
  62. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/cli.md +0 -0
  63. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/dynamic-registration.md +0 -0
  64. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/observability.md +0 -0
  65. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/requirements.md +0 -0
  66. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/testing.md +0 -0
  67. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/troubleshooting.md +0 -0
  68. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/versioning.md +0 -0
  69. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/batch_collector.py +0 -0
  70. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/bulk_insert_upsert.py +0 -0
  71. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/copy_ingest.py +0 -0
  72. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/error_handling.py +0 -0
  73. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/health_and_pool.py +0 -0
  74. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/inbox_idempotent_consumer.py +0 -0
  75. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/opentelemetry_observability.py +0 -0
  76. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/pgbouncer_mode.py +0 -0
  77. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/pipeline_mode.py +0 -0
  78. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/quickstart_async.py +0 -0
  79. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/quickstart_sync.py +0 -0
  80. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/retries_and_circuit_breaker.py +0 -0
  81. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/streaming.py +0 -0
  82. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/streaming_checkpoint_resume.py +0 -0
  83. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/sync_feature_parity.py +0 -0
  84. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/transactions_savepoints.py +0 -0
  85. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/mkdocs.yml +0 -0
  86. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/__init__.py +0 -0
  87. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/_compat.py +0 -0
  88. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/connection.py +0 -0
  89. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/database.py +0 -0
  90. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/engine.py +0 -0
  91. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/executor.py +0 -0
  92. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/health.py +0 -0
  93. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/resilience.py +0 -0
  94. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/streaming.py +0 -0
  95. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/__init__.py +0 -0
  96. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/bulk.py +0 -0
  97. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/circuit.py +0 -0
  98. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/config.py +0 -0
  99. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/__init__.py +0 -0
  100. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/base.py +0 -0
  101. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/classifier.py +0 -0
  102. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/redaction.py +0 -0
  103. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/sqlstate.py +0 -0
  104. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/idempotency_lint.py +0 -0
  105. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/keys.py +0 -0
  106. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/policies.py +0 -0
  107. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/query.py +0 -0
  108. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/result.py +0 -0
  109. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/routing.py +0 -0
  110. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_pool.py +0 -0
  111. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/__init__.py +0 -0
  112. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/_compat.py +0 -0
  113. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/connection.py +0 -0
  114. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/database.py +0 -0
  115. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/engine.py +0 -0
  116. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/executor.py +0 -0
  117. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/health.py +0 -0
  118. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/resilience.py +0 -0
  119. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/streaming.py +0 -0
  120. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/cli/__init__.py +0 -0
  121. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/cli/main.py +0 -0
  122. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/errors.py +0 -0
  123. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/batch.py +0 -0
  124. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/fastapi.py +0 -0
  125. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/inbox.py +0 -0
  126. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/__init__.py +0 -0
  127. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/logging.py +0 -0
  128. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/metrics.py +0 -0
  129. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/otel_metrics.py +0 -0
  130. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/prometheus.py +0 -0
  131. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/tracing.py +0 -0
  132. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/__init__.py +0 -0
  133. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/copy.py +0 -0
  134. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/pipeline.py +0 -0
  135. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/unnest.py +0 -0
  136. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/py.typed +0 -0
  137. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/testing/__init__.py +0 -0
  138. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/__init__.py +0 -0
  139. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/conftest.py +0 -0
  140. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/__init__.py +0 -0
  141. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/_mp_budget_worker.py +0 -0
  142. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_cli_integration.py +0 -0
  143. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_multiprocess_connection_budget.py +0 -0
  144. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_resilience_scenarios.py +0 -0
  145. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_sharding_and_replicas.py +0 -0
  146. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_throughput_paths.py +0 -0
  147. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/property/__init__.py +0 -0
  148. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/property/test_invariants.py +0 -0
  149. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/__init__.py +0 -0
  150. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/test_redaction.py +0 -0
  151. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/test_sql_injection.py +0 -0
  152. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/__init__.py +0 -0
  153. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_benchmark_stats.py +0 -0
  154. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_bulk_batch.py +0 -0
  155. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_cancellation_shielding.py +0 -0
  156. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_circuit.py +0 -0
  157. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_cli.py +0 -0
  158. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_config.py +0 -0
  159. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_default_metrics_sink.py +0 -0
  160. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_dual_api.py +0 -0
  161. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_dynamic_registration.py +0 -0
  162. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_engine_registry.py +0 -0
  163. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_errors.py +0 -0
  164. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_fastapi_integration.py +0 -0
  165. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_idempotency_lint.py +0 -0
  166. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_logging.py +0 -0
  167. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_otel_metrics.py +0 -0
  168. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_policies.py +0 -0
  169. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_prometheus_metrics.py +0 -0
  170. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_query.py +0 -0
  171. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_query_settings.py +0 -0
  172. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_resilience.py +0 -0
  173. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_result.py +0 -0
  174. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_sharding_replica.py +0 -0
  175. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_testing_fakes.py +0 -0
  176. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_tracing.py +0 -0
  177. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_unasync_translation.py +0 -0
  178. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_unnest.py +0 -0
  179. {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tools/run_unasync.py +0 -0
@@ -6,6 +6,24 @@ 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
+
9
27
  ## [0.2.0] - 2026-07-15
10
28
 
11
29
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dbkit-sql
3
- Version: 0.2.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
@@ -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.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"
@@ -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.0"
44
44
 
45
45
  __all__ = [
46
46
  "AsyncDatabase",
@@ -18,6 +18,7 @@ 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
  )
@@ -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)."""
@@ -21,6 +21,7 @@ from sqlalchemy import Connection, Engine
21
21
 
22
22
  from .._core.errors import (
23
23
  DatabaseCommitUnknownError,
24
+ DatabaseUnsupportedOperationError,
24
25
  classify,
25
26
  is_connection_error,
26
27
  )
@@ -66,6 +67,53 @@ class TransactionScope(ConnectionScope):
66
67
  else:
67
68
  nested.commit()
68
69
 
70
+ def advisory_xact_lock(self, key: int | str) -> None:
71
+ """Acquire a transaction-scoped PostgreSQL advisory lock, blocking until granted (§11.7).
72
+
73
+ The lock is held for the remainder of THIS transaction and released automatically on
74
+ ``COMMIT``/``ROLLBACK`` — there is no manual unlock, so it can never leak. It serializes
75
+ transactions that lock the same ``key``: a second locker of the same key blocks until the
76
+ first transaction ends. Nothing else is blocked (advisory locks are cooperative — they only
77
+ guard code paths that agree to take the same lock), so it is the tool for serializing a
78
+ read-modify-write on a logical entity without locking its rows.
79
+
80
+ ``key`` is either a 64-bit ``int`` (used directly as the lock key) or a ``str`` (hashed to a
81
+ ``bigint`` server-side via ``hashtextextended(key, 0)``). It is always passed as a bound
82
+ parameter — never string-interpolated.
83
+
84
+ The wait respects the transaction's ``lock_timeout`` (set via
85
+ :meth:`~dbkit.Database.transaction`'s ``lock_timeout=`` argument): a wait that exceeds
86
+ it raises :class:`~dbkit.errors.DatabaseLockTimeoutError` (retryable). PostgreSQL only;
87
+ raises :class:`~dbkit.errors.DatabaseUnsupportedOperationError` otherwise.
88
+ """
89
+ self._advisory_lock("pg_advisory_xact_lock", key, name="advisory_xact_lock")
90
+
91
+ def try_advisory_xact_lock(self, key: int | str) -> bool:
92
+ """Try to take a transaction-scoped advisory lock without blocking (§11.7).
93
+
94
+ Returns ``True`` if the lock was granted (held until this transaction ends), ``False`` if
95
+ another transaction already holds it. Never waits, so ``lock_timeout`` does not apply — use
96
+ this to fail fast (e.g. skip work another worker is already doing) instead of queuing.
97
+ ``key`` and dialect rules match :meth:`advisory_xact_lock`.
98
+ """
99
+ result = self._advisory_lock(
100
+ "pg_try_advisory_xact_lock", key, name="try_advisory_xact_lock"
101
+ )
102
+ return bool(result)
103
+
104
+ def _advisory_lock(self, func: str, key: int | str, *, name: str) -> Any:
105
+ """Run one advisory-lock function (``func`` is an internal literal, ``key`` is bound)."""
106
+ if not self._is_postgres:
107
+ raise DatabaseUnsupportedOperationError("advisory locks require PostgreSQL")
108
+ arg = "hashtextextended(:key, 0)" if isinstance(key, str) else ":key"
109
+ try:
110
+ cursor = self._conn.execute(text(f"SELECT {func}({arg})"), {"key": key})
111
+ return cursor.scalar()
112
+ except Exception as exc:
113
+ raise classify(
114
+ exc, query_name=name, database_name=self._database, role=self._role
115
+ ) from exc
116
+
69
117
 
70
118
  class _TransactionManager:
71
119
  """Async context manager implementing the transaction lifecycle (§11.1, §11.3)."""
@@ -10,12 +10,24 @@ from .inbox import (
10
10
  partitioned_inbox_ddl,
11
11
  process_once,
12
12
  )
13
+ from .outbox import (
14
+ drain,
15
+ enqueue,
16
+ outbox_ddl,
17
+ outbox_month_partition_ddl,
18
+ partitioned_outbox_ddl,
19
+ )
13
20
 
14
21
  __all__ = [
15
22
  "BatchCollector",
16
23
  "ack_after_commit",
24
+ "drain",
25
+ "enqueue",
17
26
  "inbox_ddl",
18
27
  "inbox_month_partition_ddl",
28
+ "outbox_ddl",
29
+ "outbox_month_partition_ddl",
19
30
  "partitioned_inbox_ddl",
31
+ "partitioned_outbox_ddl",
20
32
  "process_once",
21
33
  ]