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.
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/CHANGELOG.md +18 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/PKG-INFO +9 -4
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/README.md +8 -3
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/database.md +17 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/integrations.md +30 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/index.md +4 -3
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/roadmap.md +3 -2
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/security.md +2 -1
- dbkit_sql-0.3.0/examples/advisory_locks.py +42 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/run_all.py +2 -0
- dbkit_sql-0.3.0/examples/transactional_outbox.py +71 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/pyproject.toml +1 -1
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/__init__.py +1 -1
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/transaction.py +48 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/transaction.py +48 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/__init__.py +12 -0
- dbkit_sql-0.3.0/src/dbkit/integrations/outbox.py +158 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_async_integration.py +90 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_sync_integration.py +11 -0
- dbkit_sql-0.3.0/tests/unit/test_integrations_outbox.py +70 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/dependabot.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/ci.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/dependency-matrix.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/docs.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/release.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.github/workflows/security.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/.gitignore +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/CONTRIBUTING.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/LICENSE +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/Makefile +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/SECURITY.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/__main__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_common.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_results.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/_stats.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_batch_collector.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_concurrency_scaling.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_crud.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_latency.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_observability_overhead.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_overhead.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_pgbouncer_compatible.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_pool_exhaustion.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_shard_cardinality.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_streaming_scale.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_throughput.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/bench_unnest.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/check_regression.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/benchmarks/soak.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docker-compose.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/config.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/errors.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/observability.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/api/query.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/assets/logo.svg +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/cli.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/dynamic-registration.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/observability.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/requirements.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/testing.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/troubleshooting.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/docs/versioning.md +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/batch_collector.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/bulk_insert_upsert.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/copy_ingest.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/error_handling.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/health_and_pool.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/inbox_idempotent_consumer.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/opentelemetry_observability.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/pgbouncer_mode.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/pipeline_mode.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/quickstart_async.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/quickstart_sync.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/retries_and_circuit_breaker.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/streaming.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/streaming_checkpoint_resume.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/sync_feature_parity.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/examples/transactions_savepoints.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/mkdocs.yml +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/_compat.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/connection.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/database.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/engine.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/executor.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/health.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/resilience.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_async/streaming.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/bulk.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/circuit.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/config.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/base.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/classifier.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/redaction.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/errors/sqlstate.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/idempotency_lint.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/keys.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/policies.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/query.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/result.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_core/routing.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_pool.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/_compat.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/connection.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/database.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/engine.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/executor.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/health.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/resilience.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/_sync/streaming.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/cli/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/cli/main.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/errors.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/batch.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/fastapi.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/integrations/inbox.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/logging.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/metrics.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/otel_metrics.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/prometheus.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/observability/tracing.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/copy.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/pipeline.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/postgres/unnest.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/py.typed +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/src/dbkit/testing/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/conftest.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/_mp_budget_worker.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_cli_integration.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_multiprocess_connection_budget.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_resilience_scenarios.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_sharding_and_replicas.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/integration/test_throughput_paths.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/property/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/property/test_invariants.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/test_redaction.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/security/test_sql_injection.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/__init__.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_benchmark_stats.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_bulk_batch.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_cancellation_shielding.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_circuit.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_cli.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_config.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_default_metrics_sink.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_dual_api.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_dynamic_registration.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_engine_registry.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_errors.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_fastapi_integration.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_idempotency_lint.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_logging.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_otel_metrics.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_policies.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_prometheus_metrics.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_query.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_query_settings.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_resilience.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_result.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_sharding_replica.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_testing_fakes.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_tracing.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_unasync_translation.py +0 -0
- {dbkit_sql-0.2.0 → dbkit_sql-0.3.0}/tests/unit/test_unnest.py +0 -0
- {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.
|
|
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 —
|
|
399
|
-
|
|
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
|
|
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 —
|
|
330
|
-
|
|
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
|
|
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
|
|
21
|
-
|
|
22
|
-
you give it; tenant/shard authorization is
|
|
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
|
-
|
|
106
|
-
|
|
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
|
-
|
|
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())
|
|
@@ -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())
|
|
@@ -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
|
]
|