dbkit-sql 0.1.0__tar.gz → 0.2.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 (177) hide show
  1. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/CHANGELOG.md +54 -0
  2. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/PKG-INFO +23 -1
  3. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/README.md +17 -0
  4. dbkit_sql-0.2.0/docs/api/integrations.md +49 -0
  5. dbkit_sql-0.2.0/docs/dynamic-registration.md +88 -0
  6. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/testing.md +30 -0
  7. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/mkdocs.yml +1 -0
  8. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/pyproject.toml +8 -2
  9. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/__init__.py +1 -1
  10. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/connection.py +49 -1
  11. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/database.py +202 -3
  12. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/engine.py +15 -0
  13. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/executor.py +11 -0
  14. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/config.py +16 -3
  15. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/errors/__init__.py +4 -0
  16. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/errors/base.py +22 -0
  17. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/query.py +6 -0
  18. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/routing.py +20 -0
  19. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/connection.py +49 -1
  20. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/database.py +202 -3
  21. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/engine.py +15 -0
  22. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/executor.py +11 -0
  23. dbkit_sql-0.2.0/src/dbkit/integrations/fastapi.py +137 -0
  24. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/metrics.py +16 -0
  25. dbkit_sql-0.2.0/src/dbkit/testing/__init__.py +309 -0
  26. dbkit_sql-0.2.0/tests/unit/__init__.py +0 -0
  27. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_cli.py +1 -1
  28. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_config.py +8 -2
  29. dbkit_sql-0.2.0/tests/unit/test_default_metrics_sink.py +42 -0
  30. dbkit_sql-0.2.0/tests/unit/test_dynamic_registration.py +349 -0
  31. dbkit_sql-0.2.0/tests/unit/test_fastapi_integration.py +91 -0
  32. dbkit_sql-0.2.0/tests/unit/test_query_settings.py +53 -0
  33. dbkit_sql-0.2.0/tests/unit/test_testing_fakes.py +78 -0
  34. dbkit_sql-0.1.0/docs/api/integrations.md +0 -17
  35. dbkit_sql-0.1.0/src/dbkit/testing/__init__.py +0 -1
  36. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
  37. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  38. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
  39. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  40. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/dependabot.yml +0 -0
  41. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/workflows/ci.yml +0 -0
  42. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/workflows/dependency-matrix.yml +0 -0
  43. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/workflows/docs.yml +0 -0
  44. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/workflows/release.yml +0 -0
  45. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.github/workflows/security.yml +0 -0
  46. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/.gitignore +0 -0
  47. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/CONTRIBUTING.md +0 -0
  48. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/LICENSE +0 -0
  49. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/Makefile +0 -0
  50. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/SECURITY.md +0 -0
  51. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/__init__.py +0 -0
  52. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/__main__.py +0 -0
  53. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/_common.py +0 -0
  54. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/_results.py +0 -0
  55. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/_stats.py +0 -0
  56. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_batch.py +0 -0
  57. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_batch_collector.py +0 -0
  58. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_concurrency_scaling.py +0 -0
  59. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_crud.py +0 -0
  60. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_latency.py +0 -0
  61. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_observability_overhead.py +0 -0
  62. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_overhead.py +0 -0
  63. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_pgbouncer_compatible.py +0 -0
  64. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_pool_exhaustion.py +0 -0
  65. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_shard_cardinality.py +0 -0
  66. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_streaming_scale.py +0 -0
  67. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_throughput.py +0 -0
  68. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/bench_unnest.py +0 -0
  69. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/check_regression.py +0 -0
  70. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/benchmarks/soak.py +0 -0
  71. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docker-compose.yml +0 -0
  72. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/api/config.md +0 -0
  73. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/api/database.md +0 -0
  74. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/api/errors.md +0 -0
  75. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/api/observability.md +0 -0
  76. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/api/query.md +0 -0
  77. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/assets/logo.svg +0 -0
  78. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/cli.md +0 -0
  79. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/index.md +0 -0
  80. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/observability.md +0 -0
  81. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/requirements.md +0 -0
  82. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/roadmap.md +0 -0
  83. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/security.md +0 -0
  84. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/troubleshooting.md +0 -0
  85. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/docs/versioning.md +0 -0
  86. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/batch_collector.py +0 -0
  87. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/bulk_insert_upsert.py +0 -0
  88. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/copy_ingest.py +0 -0
  89. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/error_handling.py +0 -0
  90. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/health_and_pool.py +0 -0
  91. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/inbox_idempotent_consumer.py +0 -0
  92. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/opentelemetry_observability.py +0 -0
  93. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/pgbouncer_mode.py +0 -0
  94. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/pipeline_mode.py +0 -0
  95. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/quickstart_async.py +0 -0
  96. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/quickstart_sync.py +0 -0
  97. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/retries_and_circuit_breaker.py +0 -0
  98. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/run_all.py +0 -0
  99. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/streaming.py +0 -0
  100. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/streaming_checkpoint_resume.py +0 -0
  101. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/sync_feature_parity.py +0 -0
  102. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/examples/transactions_savepoints.py +0 -0
  103. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/__init__.py +0 -0
  104. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/_compat.py +0 -0
  105. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/health.py +0 -0
  106. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/resilience.py +0 -0
  107. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/streaming.py +0 -0
  108. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_async/transaction.py +0 -0
  109. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/__init__.py +0 -0
  110. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/bulk.py +0 -0
  111. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/circuit.py +0 -0
  112. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/errors/classifier.py +0 -0
  113. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/errors/redaction.py +0 -0
  114. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/errors/sqlstate.py +0 -0
  115. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/idempotency_lint.py +0 -0
  116. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/keys.py +0 -0
  117. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/policies.py +0 -0
  118. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_core/result.py +0 -0
  119. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_pool.py +0 -0
  120. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/__init__.py +0 -0
  121. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/_compat.py +0 -0
  122. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/health.py +0 -0
  123. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/resilience.py +0 -0
  124. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/streaming.py +0 -0
  125. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/_sync/transaction.py +0 -0
  126. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/cli/__init__.py +0 -0
  127. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/cli/main.py +0 -0
  128. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/errors.py +0 -0
  129. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/integrations/__init__.py +0 -0
  130. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/integrations/batch.py +0 -0
  131. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/integrations/inbox.py +0 -0
  132. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/__init__.py +0 -0
  133. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/logging.py +0 -0
  134. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/otel_metrics.py +0 -0
  135. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/prometheus.py +0 -0
  136. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/observability/tracing.py +0 -0
  137. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/postgres/__init__.py +0 -0
  138. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/postgres/copy.py +0 -0
  139. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/postgres/pipeline.py +0 -0
  140. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/src/dbkit/postgres/unnest.py +0 -0
  141. /dbkit_sql-0.1.0/tests/__init__.py → /dbkit_sql-0.2.0/src/dbkit/py.typed +0 -0
  142. {dbkit_sql-0.1.0/tests/integration → dbkit_sql-0.2.0/tests}/__init__.py +0 -0
  143. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/conftest.py +0 -0
  144. {dbkit_sql-0.1.0/tests/property → dbkit_sql-0.2.0/tests/integration}/__init__.py +0 -0
  145. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/_mp_budget_worker.py +0 -0
  146. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_async_integration.py +0 -0
  147. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_cli_integration.py +0 -0
  148. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_multiprocess_connection_budget.py +0 -0
  149. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_resilience_scenarios.py +0 -0
  150. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_sharding_and_replicas.py +0 -0
  151. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_sync_integration.py +0 -0
  152. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/integration/test_throughput_paths.py +0 -0
  153. {dbkit_sql-0.1.0/tests/security → dbkit_sql-0.2.0/tests/property}/__init__.py +0 -0
  154. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/property/test_invariants.py +0 -0
  155. {dbkit_sql-0.1.0/tests/unit → dbkit_sql-0.2.0/tests/security}/__init__.py +0 -0
  156. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/security/test_redaction.py +0 -0
  157. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/security/test_sql_injection.py +0 -0
  158. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_benchmark_stats.py +0 -0
  159. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_bulk_batch.py +0 -0
  160. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_cancellation_shielding.py +0 -0
  161. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_circuit.py +0 -0
  162. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_dual_api.py +0 -0
  163. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_engine_registry.py +0 -0
  164. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_errors.py +0 -0
  165. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_idempotency_lint.py +0 -0
  166. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_logging.py +0 -0
  167. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_otel_metrics.py +0 -0
  168. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_policies.py +0 -0
  169. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_prometheus_metrics.py +0 -0
  170. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_query.py +0 -0
  171. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_resilience.py +0 -0
  172. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_result.py +0 -0
  173. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_sharding_replica.py +0 -0
  174. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_tracing.py +0 -0
  175. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_unasync_translation.py +0 -0
  176. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tests/unit/test_unnest.py +0 -0
  177. {dbkit_sql-0.1.0 → dbkit_sql-0.2.0}/tools/run_unasync.py +0 -0
@@ -6,6 +6,60 @@ All notable changes to this project are documented here. The format is based on
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.2.0] - 2026-07-15
10
+
11
+ ### Added
12
+ - `AsyncDatabase.ensure_database(name, config)` — idempotent registration: no-op when the
13
+ config is unchanged (lock-free, a few µs), (re)registers when missing or changed. Safe to
14
+ call in front of every query; config changes (including password-only rotations) take
15
+ effect in place with old engines disposed.
16
+ - **Dynamic-first configs**: an explicit empty ``databases: {}`` mapping is now valid —
17
+ services that discover every DSN at runtime bootstrap with no static databases. A missing
18
+ ``databases`` key is still rejected.
19
+ - **Dynamic database registration**: `AsyncDatabase.register_database(name, config)` /
20
+ `unregister_database(name)` (sync mirror included) — register shard/tenant databases whose
21
+ DSNs are discovered at runtime (e.g. from a service registry), without a service-side engine
22
+ registry. Copy-on-write config swap (readers never see a partial mapping), single-flight
23
+ registration lock, engine + limiter + breaker cleanup on replace/unregister, replica-selector
24
+ updates, and eager engine creation for `required` primaries when already started.
25
+ - `AsyncDatabase.database_scope(name, config)` — context-manager form: register for the
26
+ duration of a block (tests, migrations, one-off tenant jobs), auto-unregister + dispose on
27
+ exit. Documented anti-pattern: never scope per request — that defeats pooling; services
28
+ register long-lived shards once.
29
+ - `DatabaseConfig.from_dict(...)` — build one database config from the same dict shape as a
30
+ `databases` entry.
31
+ - `AsyncEngineRegistry.dispose_database(name)` and `ResilientExecutor.forget_database(name)`.
32
+ - `RoundRobinReplicaSelector.set_replicas(...)` / `WeightedReplicaSelector.set_replicas(...)`
33
+ for runtime replica updates.
34
+ - `dbkit.errors.OVERLOAD_CATEGORIES` / `TIMEOUT_CATEGORIES` — canonical category groupings for
35
+ HTTP mapping (503-retryable vs 504) so services stop hand-rolling exception lists.
36
+ - **`dbkit.integrations.fastapi`**: `install_exception_handlers(app)` maps `DatabaseError` by
37
+ category to RFC 7807 responses — 503 + `Retry-After` for overload, 504 for timeouts, 500 for
38
+ bugs. New optional extra: `dbkit-sql[fastapi]` (Starlette only, imported lazily).
39
+ - `py.typed` marker — mypy-strict consumers now get real types instead of `Any`.
40
+ - **`Query.settings`** — per-query, transaction-local PostgreSQL settings (e.g.
41
+ ``{"jit": "off"}``, ``{"work_mem": "64MB"}``) applied via parameterized
42
+ ``set_config(name, value, true)`` right before the statement; names validated, values bound,
43
+ never leaks past the statement's transaction.
44
+ - **`dbkit.testing`**: `FakeAsyncDatabase` / `FakeDatabase` — in-memory test doubles that
45
+ record every call (name, statement, params, target, settings, in_transaction) and return
46
+ queued rows; dynamic-registration tracking included.
47
+ - **`max_databases`** config — LRU cap on dynamically registered databases: beyond it the
48
+ least-recently-ensured dynamic database is fully purged (engines, limiter, breakers,
49
+ selector entry). Static databases are never evicted.
50
+ - `install_exception_handlers(..., database=db)` — the 503 ``Retry-After`` header now derives
51
+ from the circuit breaker's ``open_seconds`` when a facade is provided.
52
+ - Docs: new "Dynamic Registration" guide; FastAPI/`Query.settings` sections in the
53
+ integrations reference; `dbkit.testing` section in Testing & Benchmarks.
54
+
55
+ ### Fixed
56
+ - ``observability.metrics: true`` (the default) now actually wires a Prometheus sink when
57
+ ``prometheus_client`` is installed — previously the default was silently no-op. The sink is a
58
+ process-wide singleton so multiple facades share collectors safely.
59
+ - Dynamic registration now enforces the process-wide connection budget at admission time
60
+ (``connection_budget.maximum_per_process`` + ``enforce_at_startup``) — a runtime-registered
61
+ database can no longer push the process past its configured ceiling.
62
+
9
63
  ## [0.1.0] - 2026-07-15
10
64
 
11
65
  First public release on PyPI as `dbkit-sql` (import name: `dbkit`).
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dbkit-sql
3
- Version: 0.1.0
3
+ Version: 0.2.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
@@ -393,6 +398,23 @@ tracking), and LRU engine eviction bounded by `max_engines` so a dynamic or unbo
393
398
  space still keeps a bounded number of live connections. No cross-shard transactions — pair with
394
399
  an outbox/saga pattern for multi-shard writes.
395
400
 
401
+ ### Dynamic registration (0.2)
402
+
403
+ Databases whose DSNs are discovered at runtime (per-tenant shards from a service registry,
404
+ rotated credentials) register on the fly — no application-side engine registry:
405
+
406
+ ```python
407
+ db = AsyncDatabase.from_config({"databases": {}, "max_databases": 500}) # dynamic-first
408
+
409
+ await db.ensure_database(shard, {"primary": {"url": dsn}}) # lock-free no-op when unchanged
410
+ rows = await db.fetch_all(query, params, target=DatabaseTarget(database=shard, role="read"))
411
+ ```
412
+
413
+ Changed configs (host moves, password rotations) re-register in place with old engines
414
+ disposed; `max_databases` LRU-evicts idle dynamic shards; registration respects the
415
+ process-wide connection budget. See the
416
+ [Dynamic Registration guide](https://talaatmagdyx.github.io/dbkit-sql/dynamic-registration/).
417
+
396
418
  ## Building blocks, batteries included
397
419
 
398
420
  | Building block | Job |
@@ -329,6 +329,23 @@ tracking), and LRU engine eviction bounded by `max_engines` so a dynamic or unbo
329
329
  space still keeps a bounded number of live connections. No cross-shard transactions — pair with
330
330
  an outbox/saga pattern for multi-shard writes.
331
331
 
332
+ ### Dynamic registration (0.2)
333
+
334
+ Databases whose DSNs are discovered at runtime (per-tenant shards from a service registry,
335
+ rotated credentials) register on the fly — no application-side engine registry:
336
+
337
+ ```python
338
+ db = AsyncDatabase.from_config({"databases": {}, "max_databases": 500}) # dynamic-first
339
+
340
+ await db.ensure_database(shard, {"primary": {"url": dsn}}) # lock-free no-op when unchanged
341
+ rows = await db.fetch_all(query, params, target=DatabaseTarget(database=shard, role="read"))
342
+ ```
343
+
344
+ Changed configs (host moves, password rotations) re-register in place with old engines
345
+ disposed; `max_databases` LRU-evicts idle dynamic shards; registration respects the
346
+ process-wide connection budget. See the
347
+ [Dynamic Registration guide](https://talaatmagdyx.github.io/dbkit-sql/dynamic-registration/).
348
+
332
349
  ## Building blocks, batteries included
333
350
 
334
351
  | Building block | Job |
@@ -0,0 +1,49 @@
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
+ ::: dbkit.integrations.BatchCollector
18
+
19
+ ## HTTP APIs (FastAPI / Starlette)
20
+
21
+ Category-driven RFC 7807 responses for unhandled `DatabaseError`s: overload
22
+ (pool timeout, limiter, circuit open, backend unreachable) → **503** with a
23
+ `Retry-After` header (derived from the circuit breaker's `open_seconds` when you
24
+ pass your facade); query timeouts → **504**; programming/integrity errors stay
25
+ **500** and loud. Requires the `dbkit-sql[fastapi]` extra (Starlette only).
26
+
27
+ ```python
28
+ from dbkit.integrations.fastapi import install_exception_handlers
29
+
30
+ install_exception_handlers(app, database=db)
31
+ ```
32
+
33
+ ::: dbkit.integrations.fastapi.install_exception_handlers
34
+
35
+ ## Per-query session settings
36
+
37
+ `Query.settings` applies transaction-local PostgreSQL settings right before the
38
+ statement — parameterized `set_config(name, value, true)`, names validated:
39
+
40
+ ```python
41
+ COUNTS = Query(
42
+ name="inbox.counts",
43
+ statement=sql("SELECT ..."),
44
+ settings={"jit": "off"}, # or {"work_mem": "64MB"} for a heavy aggregate
45
+ )
46
+ ```
47
+
48
+ The setting never leaks: it resets when the statement's transaction ends, before
49
+ 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
@@ -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)
@@ -9,6 +9,7 @@ docs_dir: docs
9
9
 
10
10
  nav:
11
11
  - Home: index.md
12
+ - Dynamic Registration: dynamic-registration.md
12
13
  - CLI: cli.md
13
14
  - API Reference:
14
15
  - Database (async/sync): api/database.md
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dbkit-sql"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "A thin, high-throughput SQL toolkit over SQLAlchemy Core — sync and async, ORM-free."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -37,8 +37,14 @@ pydantic = ["pydantic>=2.7"]
37
37
  orjson = ["orjson>=3.10"]
38
38
  cli = ["typer>=0.12"]
39
39
  bench = ["psutil>=5.9"]
40
+ # RFC 7807 exception handlers for FastAPI/Starlette apps (dbkit.integrations.fastapi)
41
+ fastapi = ["starlette>=0.37"]
40
42
  dev = [
41
- "dbkit-sql[psycopg,asyncpg,yaml,prometheus,pydantic,bench,otel,cli]",
43
+ "dbkit-sql[psycopg,asyncpg,yaml,prometheus,pydantic,bench,otel,cli,fastapi]",
44
+ # starlette 1.x TestClient requires httpx2 (0.x used httpx). Keep dev on a
45
+ # current, CVE-free starlette; the runtime [fastapi] extra stays permissive.
46
+ "starlette>=1.3.1",
47
+ "httpx2",
42
48
  "pytest>=8.2",
43
49
  "pytest-asyncio>=0.23",
44
50
  "pytest-cov>=5.0",
@@ -40,7 +40,7 @@ from ._core.routing import (
40
40
  )
41
41
  from ._sync.database import Database
42
42
 
43
- __version__ = "0.1.0"
43
+ __version__ = "0.2.0"
44
44
 
45
45
  __all__ = [
46
46
  "AsyncDatabase",
@@ -11,6 +11,7 @@ mapping, timeouts, and error classification live in exactly one place.
11
11
  from __future__ import annotations
12
12
 
13
13
  import contextlib
14
+ import re
14
15
  from collections.abc import Mapping, Sequence
15
16
  from typing import Any
16
17
 
@@ -20,7 +21,12 @@ from sqlalchemy.exc import MultipleResultsFound, NoResultFound
20
21
  from sqlalchemy.ext.asyncio import AsyncConnection
21
22
 
22
23
  from .._core import result as result_mod
23
- from .._core.errors import DatabaseResultError, classify
24
+ from .._core.errors import (
25
+ DatabaseProgrammingError,
26
+ DatabaseResultError,
27
+ DatabaseUnsupportedOperationError,
28
+ classify,
29
+ )
24
30
  from .._core.query import Query, Statement, coerce_statement
25
31
  from ._compat import IS_ASYNC, pipeline_scope, timeout_scope
26
32
 
@@ -36,6 +42,30 @@ def apply_statement_timeout_sql(seconds: float | None) -> str | None:
36
42
  return f"SET LOCAL statement_timeout = {ms}"
37
43
 
38
44
 
45
+ _SETTING_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.]*$")
46
+
47
+
48
+ async def _apply_local_settings(
49
+ conn: AsyncConnection, settings: Mapping[str, str] | None, *, is_postgres: bool
50
+ ) -> None:
51
+ """Apply ``Query.settings`` with transaction-local scope (§12.4).
52
+
53
+ Uses parameterized ``set_config(name, value, true)`` so values are never
54
+ interpolated; setting names are whitelist-validated. PostgreSQL only.
55
+ """
56
+ if not settings:
57
+ return
58
+ if not is_postgres:
59
+ raise DatabaseUnsupportedOperationError("Query.settings requires PostgreSQL")
60
+ for name, value in settings.items():
61
+ if not _SETTING_NAME_RE.fullmatch(name):
62
+ raise DatabaseProgrammingError(f"invalid setting name in Query.settings: {name!r}")
63
+ await conn.execute(
64
+ text("SELECT set_config(:setting_name, :setting_value, true)"),
65
+ {"setting_name": name, "setting_value": str(value)},
66
+ )
67
+
68
+
39
69
  async def _maybe_set_timeout(
40
70
  conn: AsyncConnection, seconds: float | None, *, is_postgres: bool
41
71
  ) -> None:
@@ -212,6 +242,9 @@ class AsyncConnectionScope:
212
242
  """Run a read and return every row, mapped to ``map_to`` (no cardinality check)."""
213
243
  statement, _q, timeout, name = self._resolve(query, params)
214
244
  try:
245
+ await _apply_local_settings(
246
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
247
+ )
215
248
  rows = await run_fetch(
216
249
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
217
250
  )
@@ -227,6 +260,9 @@ class AsyncConnectionScope:
227
260
  """Run a read expecting exactly one row; raises :class:`DatabaseResultError` otherwise."""
228
261
  statement, _q, timeout, name = self._resolve(query, params)
229
262
  try:
263
+ await _apply_local_settings(
264
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
265
+ )
230
266
  row = await run_fetch_one(
231
267
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
232
268
  )
@@ -256,6 +292,9 @@ class AsyncConnectionScope:
256
292
  """Run a read expecting zero or one row; ``None`` if empty, else the mapped row."""
257
293
  statement, _q, timeout, name = self._resolve(query, params)
258
294
  try:
295
+ await _apply_local_settings(
296
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
297
+ )
259
298
  row = await run_fetch_optional(
260
299
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
261
300
  )
@@ -278,6 +317,9 @@ class AsyncConnectionScope:
278
317
  """Run a read expecting exactly one row and return its first column."""
279
318
  statement, _q, timeout, name = self._resolve(query, params)
280
319
  try:
320
+ await _apply_local_settings(
321
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
322
+ )
281
323
  return await run_fetch_value(
282
324
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
283
325
  )
@@ -306,6 +348,9 @@ class AsyncConnectionScope:
306
348
  """Run a read and return the first column of every row."""
307
349
  statement, _q, timeout, name = self._resolve(query, params)
308
350
  try:
351
+ await _apply_local_settings(
352
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
353
+ )
309
354
  return await run_fetch_values(
310
355
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
311
356
  )
@@ -318,6 +363,9 @@ class AsyncConnectionScope:
318
363
  """Run a write/DDL statement and return the affected row count."""
319
364
  statement, _q, timeout, name = self._resolve(query, params)
320
365
  try:
366
+ await _apply_local_settings(
367
+ self._conn, _q.settings if _q else None, is_postgres=self._is_postgres
368
+ )
321
369
  cursor = await run_execute(
322
370
  self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
323
371
  )