pgbulkhead 0.1.0__tar.gz

pgbulkhead-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

pgbulkhead-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/). Until 1.0, a minor version may change the API.
+
+## [0.1.0] - 2026-11-11
+
+First release.
+
+- `TenancyModel`: a tenant column (the hard wall), an optional workspace column (the soft
+  wall), the settings namespace, and an opt-in `GucBypass` or `RoleBypass` across the workspace
+  wall only.
+- `policy_sql` / `policy_statements`: forced row-level security policies, per command for a
+  model with a workspace (reads span the readable set, writes bind the active workspace) and a
+  single policy for a single-key model. Idempotent, and names are validated before they reach
+  DDL.
+- `SecurityContext`, `context_from_claims`: the verified identity, failing closed on a missing
+  tenant or workspace.
+- `scoped_session`, `system_session`, `transaction`, `bind_context`: transaction-local binding
+  with a cancel-safe exit.
+- `SecuredDatabase`, `PoolSettings`, `WorkspaceLimiter`: per-workspace admission sized together
+  with the pool, with `Overloaded` refusals whose text a server can replace.
+
+[0.1.0]: https://github.com/NimbleBrainInc/pgbulkhead/releases/tag/v0.1.0

pgbulkhead-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pgbulkhead-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+pgbulkhead
+Copyright 2026 NimbleBrain, Inc.
+
+This product includes software developed at NimbleBrain, Inc.

pgbulkhead-0.1.0/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.5
+Name: pgbulkhead
+Version: 0.1.0
+Summary: Tenant isolation for multi-tenant MCP servers on Postgres. One database, many tenants and workspaces: Postgres enforces the walls, and no agent can talk its way through them.
+Project-URL: Homepage, https://github.com/NimbleBrainInc/pgbulkhead
+Project-URL: Issues, https://github.com/NimbleBrainInc/pgbulkhead/issues
+Project-URL: Changelog, https://github.com/NimbleBrainInc/pgbulkhead/blob/main/CHANGELOG.md
+Author: NimbleBrain, Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,mcp,multi-tenant,postgres,row-level-security,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.4
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36
+Description-Content-Type: text/markdown
+
+# pgbulkhead
+
+Tenant isolation for multi-tenant MCP servers on Postgres. One database, many tenants and
+workspaces: Postgres enforces the walls, and no agent can talk its way through them.
+
+- **Identity no prompt can steer.** Tenant and workspace come only from a verified context
+  (a token your server checked, or headers a gateway set), never from tool arguments. Row-level
+  security does the filtering, so a query that forgets its `WHERE tenant_id = ...` still sees
+  only its own tenant.
+- **Fair sharing under agent fan-out.** Calls are admitted per workspace before they take a
+  connection, so one agent loop firing fifty calls queues behind its own workspace's slots
+  instead of taking the pool from everyone else.
+- **Cancel-safe sessions.** Host timeouts and dropped clients cancel calls mid-transaction. Each
+  session rolls back and returns its connection under a shield, so cancellations don't leak
+  connections.
+- **Errors an agent can act on.** An overloaded call is refused before it runs anything, with a
+  message that says so, so the agent knows a retry is safe.
+
+It is for Python MCP servers (FastMCP or any other, on async SQLAlchemy) that serve more than
+one customer from one Postgres database. It needs nothing else.
+
+**What it is not.** Not a Postgres extension: it renders ordinary row-level security policies
+and sets ordinary settings. Not an ORM: you write your queries with SQLAlchemy as usual. Not for
+Django or sync SQLAlchemy. Not for a database per tenant. Not proof against arbitrary SQL run as
+your app role; see [the threat model](#threat-model).
+
+```sh
+pip install pgbulkhead        # or: uv add pgbulkhead
+```
+
+Python 3.12+, SQLAlchemy 2 (asyncio), any async Postgres driver (tested with asyncpg), Postgres
+14+.
+
+## How it works
+
+You describe your walls once, as a `TenancyModel`. A migration renders its policies onto each
+table. Every request opens a session with its verified context bound, and Postgres filters every
+row it reads or writes.
+
+```python
+from pgbulkhead import TenancyModel, policy_statements
+
+# tenant_id is the hard wall; workspace_id is a soft wall inside it.
+MODEL = TenancyModel(namespace="notes")
+
+# In an alembic migration, after creating the table:
+for statement in policy_statements(MODEL, "note"):
+    op.execute(statement)
+```
+
+That table now admits a row only when its `tenant_id` matches the session's tenant. Reads span
+the workspaces the session may read; writes go to its active workspace only. A session that
+bound nothing sees no rows and can write none.
+
+At request time, build the context from what you verified and open a session:
+
+```python
+from pgbulkhead import SecuredDatabase, SecurityContext, context_from_claims
+
+db = SecuredDatabase(model=MODEL, url_env="NOTES_DATABASE_URL", prefix="NOTES")
+db.check()  # at startup: settings validated, so a bad value fails the deploy, not a call
+
+@mcp.tool()
+async def list_notes() -> list[dict]:
+    ctx = context_from_claims(verified_claims())  # from your auth layer, never from arguments
+    async with db.session(ctx) as conn:
+        rows = await conn.execute(select(note))    # only this tenant's readable workspaces
+        return [dict(r._mapping) for r in rows]
+```
+
+`db.session` admits the call against its workspace's concurrency limit, checks out a connection,
+binds the context inside a transaction, and commits or rolls back on the way out.
+
+## Threat model
+
+**The guarantee.** Isolation holds against query bugs and against identity taken from untrusted
+input. It does not hold against arbitrary SQL execution in the app role.
+
+What that means in practice:
+
+- **Query bugs.** A missing `WHERE`, a wrong join, an unscoped `UPDATE`: Postgres applies the
+  policy to every statement, so the mistake returns or touches only rows the session's context
+  allows.
+- **Identity from untrusted input.** The context is built from a verified source, so text an
+  agent writes (tool arguments, a request body, anything a prompt can steer) cannot choose the
+  tenant. Never build a `SecurityContext` from tool arguments: the model writes them, and anyone
+  who can put text in front of the model can steer what it writes.
+- **Arbitrary SQL in the app role: not covered.** The context lives in Postgres settings the
+  session sets with `set_config`. The app role can set any of them, `<namespace>.tenant_id`
+  included, so SQL that runs as the app role without going through your code (SQL injection, or
+  a tool that executes model-written SQL) can move its own session to another tenant.
+  `tests/test_isolation.py::test_arbitrary_sql_in_the_app_role_is_outside_the_guarantee`
+  demonstrates it. If you run model-written SQL, run it as a separate role with no access to
+  these tables, or give each tenant its own role or database.
+
+What the guarantee rests on, all of which is yours to provision:
+
+1. **The app role is not a superuser and not `BYPASSRLS`.** Either one silently voids every
+   policy. Create it with `NOSUPERUSER NOBYPASSRLS`.
+2. **The app role does not own the tables**, or the policies are `FORCE`d. The rendered DDL
+   forces them, so the owner is bound too, but keep migrations and serving on separate roles
+   anyway.
+3. **Every table holding tenant data has the policy.** Row-level security is per table and does
+   not follow foreign keys, so a child table carries the tenant (and workspace) columns and its
+   own policy. A table without one is unprotected.
+4. **The context comes from a verified source.** Everything above is moot if the tenant is read
+   from a tool argument.
+
+Settings are bound with `set_config(name, value, true)` inside a transaction, as bound
+parameters, so they end with the transaction and a pooled connection never carries one request's
+tenant into the next.
+
+## Policy shapes
+
+**Per-command** (the default: a tenant column and a workspace column). Four policies, one per
+command, because a single `FOR ALL` policy cannot keep a read grant from deleting: Postgres
+never applies `WITH CHECK` to `DELETE`, and `USING` picks the rows an `UPDATE` or `DELETE` may
+touch. Split, the read predicate governs `SELECT` only, and every write is bound to the active
+workspace both on the row it selects and on the row it writes.
+
+**Single-key** (`workspace_column=None`). One policy scoping reads and writes on the tenant
+alone. Use it for a tenant-wide fact (an opt-out list, an audit log) that every workspace of the
+tenant shares, or for a service whose only wall is one key:
+
+```python
+LEDGER = TenancyModel(workspace_column=None, namespace="notes")
+ORGS = TenancyModel(tenant_column="org_id", workspace_column=None, namespace="notes")
+```
+
+**Mixing shapes fails closed.** Each policy reads only its own settings, and an unset setting
+reads as NULL, so a session bound for one model matches no row of a table under another. Getting
+it wrong returns nothing, never the wrong rows.
+
+Re-rendering is idempotent: the DDL drops its own policy names (and, by default, the other
+shape's) before creating them, so a migration can switch a table between shapes.
+
+## Crossing the workspace wall
+
+Some jobs (a reconciler, a nightly sweep) must read every workspace of a tenant. A model can
+allow that with a bypass. **It is off unless you set one, and no bypass crosses the tenant
+wall.**
+
+| Bypass | How a session takes it | Who can take it |
+|---|---|---|
+| `GucBypass()` | `system_session(engine, model, tenant_id)` sets `<namespace>.role = 'system'` | anything that can run SQL as the app role, so it has the same exposure as the tenant setting |
+| `RoleBypass("reconciler")` | connect as a login role that is a member of `reconciler` | only that role; SQL running as the app role cannot take it |
+
+Prefer `RoleBypass` when the privileged path should be out of the app role's reach. Never grant
+the bypass role to the app role.
+
+```python
+SWEEP = TenancyModel(namespace="notes", bypass=RoleBypass("notes_reconciler"))
+# The job uses its own engine, logging in as a member of notes_reconciler, and binds a tenant:
+async with scoped_session(job_engine, SWEEP, SecurityContext("tenant-a", "any")) as conn:
+    ...  # every workspace of tenant-a, and nothing of any other tenant
+```
+
+## Admission and the pool
+
+A server serving many workspaces from one pool sizes the pool and admits calls per workspace,
+so a burst from one workspace waits for its own slots. Settings are read once from
+`<PREFIX>_…`:
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `DB_POOL_SIZE` | 5 | connections the pool keeps open |
+| `DB_POOL_MAX_OVERFLOW` | 5 | connections it may open past that under load |
+| `DB_POOL_TIMEOUT_SECONDS` | 10 | how long a checkout waits; past it, `PoolExhausted` |
+| `WORKSPACE_CONCURRENCY` | 2 | calls one workspace runs at once per process |
+| `WORKSPACE_WAIT_SECONDS` | 15 | how long a call over that waits for a slot; past it, `WorkspaceBusy` |
+
+A call holds at most two connections (its session, and one write committed apart from it), so
+`2 × WORKSPACE_CONCURRENCY` must stay below `DB_POOL_SIZE + DB_POOL_MAX_OVERFLOW`, or one
+workspace could hold every connection. `PoolSettings` refuses settings that break that, so call
+`db.check()` at startup and a bad value fails the deploy rather than a user's call. A server
+with more traffic passes its own `defaults=PoolSettings(...)`; the environment still overrides
+them.
+
+Admit a call's own session only (`db.session`). A second session it opens while holding a slot
+(`db.unadmitted_session`) is not admitted, or a workspace whose every slot waits on a second
+session would deadlock. To run several sessions in turn under one slot, use
+`async with db.admitted(ctx) as slot:` and `slot.session()`. A checkout timeout in
+`slot.session()` raises the pool's own `TimeoutError`, not `PoolExhausted`: an earlier session
+under the slot may have committed, so the request is not safe to retry as a whole.
+
+**Overload errors.** `WorkspaceBusy` and `PoolExhausted` are both `Overloaded`, and the call ran
+nothing. Each carries `message` and `next_step` text you can return to the agent as they are;
+map them onto your error surface as a rate limit. Replace the text per server:
+
+```python
+from pgbulkhead import Overloaded, RefusalText, WorkspaceBusy
+
+db = SecuredDatabase(
+    model=MODEL, url_env="NOTES_DATABASE_URL", prefix="NOTES",
+    refusals={
+        WorkspaceBusy: RefusalText("This notebook has too many requests running.", "Retry in a few seconds."),
+        Overloaded: RefusalText("The notes service is busy.", "Retry in a few seconds."),
+    },
+)
+```
+
+## Cancellation
+
+An MCP call runs under a cancel scope, and a cancelled scope raises again at every await inside
+it, including the session's own rollback. Unshielded, SQLAlchemy then terminates the connection
+instead of returning it, and every cancelled call costs the pool one. Each session here ends its
+transaction and returns its connection inside a shielded scope bounded by
+`CLEANUP_TIMEOUT_SECONDS` (10s) per step. Past the bound, a rollback is abandoned and the
+connection discarded, and a commit raises `TimeoutError`, because its writes may or may not
+have landed.
+
+A query interrupted in flight is the one loss left: the driver discards that connection itself,
+because its protocol state is unknown. Nothing stays checked out either way.
+`tests/test_session_cancel.py` proves both against a real Postgres.
+
+## API
+
+| Name | What it is |
+|---|---|
+| `TenancyModel` | the walls: tenant column, optional workspace column, settings namespace, bypass |
+| `GucBypass`, `RoleBypass` | the two ways to let a session cross the workspace wall |
+| `policy_sql`, `policy_statements` | a table's policy DDL, as one string or one statement each |
+| `SecurityContext` | one request's verified tenant, workspace, read grants and scopes |
+| `context_from_claims`, `ClaimNames` | a context from verified token claims, fail closed |
+| `scoped_session` | a transaction with a context bound, refusing an empty identity |
+| `system_session` | a transaction through a `GucBypass`, optionally bound to one tenant |
+| `transaction`, `bind_context`, `check_context` | the shielded transaction alone, the binding alone, and the check `scoped_session` runs before it |
+| `SecuredDatabase` | one server's model, engine, pool settings and limiter |
+| `PoolSettings`, `create_pooled_engine` | pool and admission settings, validated together |
+| `WorkspaceLimiter`, `admitted_session` | per-workspace admission, for a server not using `SecuredDatabase` |
+| `Overloaded`, `WorkspaceBusy`, `PoolExhausted`, `RefusalText` | refusals, and replacement text |
+| `pgbulkhead.testing.use_limiter` | run a database's sessions under a small limiter in tests |
+
+## Development
+
+```sh
+docker run -d --rm -p 127.0.0.1:5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:16-alpine
+make verify     # ruff format check, ruff lint, ty, pytest
+```
+
+The database suites need a disposable Postgres with a superuser at `PGBULKHEAD_TEST_URL`
+(default `postgresql+asyncpg://postgres@127.0.0.1:5432/postgres`); they create and drop their
+own roles and tables. Without one they skip locally and fail under CI.
+
+## Releasing
+
+1. In a pull request, set `version` in `pyproject.toml` and date its `CHANGELOG.md` entry.
+2. After it merges, tag the merge commit `v<version>` and push the tag.
+3. `release.yml` builds once, then waits for approval of the `pypi` environment. Download the
+   run's `dist` artifact (the exact files PyPI will receive), install the wheel in a clean
+   environment, and run the suite against it.
+4. A maintainer approves the deployment, and those files go to PyPI. A version can never be
+   uploaded twice, so step 3 is the last chance to catch a broken release.
+
+Publishing uses trusted publishing (OIDC); there is no API token to rotate or leak.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Security reports: [SECURITY.md](SECURITY.md).