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