Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(db): address review on the tenant model migration (CHOO-2623)

Wojciech Wojtyniak3255a72754df
diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.py
index 8e5390d33..a0c481c26 100644
--- a/core/switch_core/bridges/agent/protocol/service.py
+++ b/core/switch_core/bridges/agent/protocol/service.py
@@ -337,8 +337,9 @@ class ProtocolService:
InvalidIconUrl: ``icon_url`` is malformed or points somewhere unsafe.
InvalidDisplayName: ``display_name`` is over-long or unsafe to render.
AgentExistsError: agent with this name exists and ``overwrite`` is
- False, or the existing agent is owned by another user (the name
- is global, but re-registration stays within the owner's tenant).
+ False, or the existing agent is owned by another user
+ (``agents.name`` is unique per tenant, but re-registration
+ stays within the owner's tenant).
"""
if not _VALID_NAME_RE.match(name):
raise ValueError(
@@ -367,12 +368,13 @@ class ProtocolService:
"replaces integration profile)."
)
if existing and existing.owner_id != owner_id:
- # Agent names are a global namespace, but re-registration must
- # stay inside the caller's own tenant. Overwriting an agent
- # owned by someone else would mint the caller a live API key for
- # that agent (whose owner_id is left unchanged) and delete the
- # real owner's key, i.e. a cross-tenant takeover. Report it as a
- # plain name clash so ownership is never disclosed.
+ # `agents.name` is unique per tenant, not globally, but
+ # re-registration must still stay inside the caller's own
+ # tenant. Overwriting an agent owned by someone else would mint
+ # the caller a live API key for that agent (whose owner_id is
+ # left unchanged) and delete the real owner's key, i.e. a
+ # cross-tenant takeover. Report it as a plain name clash so
+ # ownership is never disclosed.
raise AgentExistsError(
f"Agent already exists: {name!r}. "
"Pass overwrite=True to re-register (rotates API key, "
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 7f215c97e..848fe0646 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -20,7 +20,7 @@ from sqlalchemy import (
text,
)
from sqlalchemy.dialects.postgresql import JSONB
-from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.orm import Mapped, declared_attr, mapped_column
from switch_core.db.base import Base
from switch_core.db.notify_ddl import (
@@ -94,11 +94,27 @@ class TenantScoped:
today — so an ordinary ORM insert needs no change to land in the right
place. A later PR replaces this default with a value read from the
request/session context; nothing here reads from a contextvar yet.
+
+ The foreign key is named explicitly (`fk_<table>_tenant`) rather than left
+ for the dialect to default, because `declared_attr` gives each subclass
+ its own column and an unnamed constraint would default to
+ `<table>_tenant_id_fkey` — a different name than the migration gives the
+ same constraint, which would make a schema built by `create_all` disagree
+ with one built by Alembic and break the migration's `downgrade` against
+ the former.
"""
- tenant_id: Mapped[str] = mapped_column(
- Text, ForeignKey("tenants.id"), nullable=False, default=TENANT_ZERO_ID
- )
+ @declared_attr
+ def tenant_id(cls) -> Mapped[str]: # noqa: N805 - SQLAlchemy convention
+ return mapped_column(
+ Text,
+ ForeignKey(
+ "tenants.id",
+ name=f"fk_{cls.__tablename__}_tenant", # type: ignore[attr-defined]
+ ),
+ nullable=False,
+ default=TENANT_ZERO_ID,
+ )
# ── Users ──────────────────────────────────────────────────────────────────────
@@ -371,7 +387,7 @@ agent_skills = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_agent_skills_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -426,7 +442,7 @@ room_agents = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_room_agents_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -460,7 +476,7 @@ room_skills = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_room_skills_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -680,7 +696,7 @@ room_references = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_room_references_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -704,7 +720,7 @@ room_documents = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_room_documents_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -756,7 +772,10 @@ class ReferenceType(TenantScoped, Base):
__tablename__ = "reference_types"
tenant_id: Mapped[str] = mapped_column(
- Text, ForeignKey("tenants.id"), primary_key=True, default=TENANT_ZERO_ID
+ Text,
+ ForeignKey("tenants.id", name="fk_reference_types_tenant"),
+ primary_key=True,
+ default=TENANT_ZERO_ID,
)
type: Mapped[str] = mapped_column(Text, primary_key=True)
owner_id: Mapped[str] = mapped_column(Text, ForeignKey("users.id"), nullable=False)
@@ -821,7 +840,7 @@ room_packages = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_room_packages_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -845,7 +864,7 @@ package_references = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_package_references_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
@@ -869,7 +888,7 @@ package_documents = Table(
Column(
"tenant_id",
Text,
- ForeignKey("tenants.id"),
+ ForeignKey("tenants.id", name="fk_package_documents_tenant"),
nullable=False,
default=TENANT_ZERO_ID,
),
diff --git a/core/switch_core/db/stores/reference_type_store.py b/core/switch_core/db/stores/reference_type_store.py
index 4a5455667..fa29a2a08 100644
--- a/core/switch_core/db/stores/reference_type_store.py
+++ b/core/switch_core/db/stores/reference_type_store.py
@@ -15,6 +15,8 @@ class ReferenceTypeStore:
session.add(reference_type)
await session.flush()
except IntegrityError as exc:
+ # TODO(next PR): scope to the request's tenant instead of matching
+ # across all of them.
clash = await session.execute(
select(ReferenceType.type).where(
ReferenceType.type == reference_type.type
@@ -34,6 +36,8 @@ class ReferenceTypeStore:
async def get_many(
self, session: AsyncSession, types: list[str]
) -> list[ReferenceType]:
+ # TODO(next PR): scope to the request's tenant instead of matching
+ # across all of them.
if not types:
return []
result = await session.execute(
@@ -50,6 +54,8 @@ class ReferenceTypeStore:
``owner_id = NULL`` comparison is never true in SQL, so it is left out
rather than relied on.
"""
+ # TODO(next PR): scope to the request's tenant instead of matching
+ # across all of them.
condition: ColumnElement[bool]
if user_id is None:
condition = ReferenceType.read_visibility == "public"
@@ -62,6 +68,8 @@ class ReferenceTypeStore:
return list(result.scalars().all())
async def list_all(self, session: AsyncSession) -> list[ReferenceType]:
+ # TODO(next PR): scope to the request's tenant instead of matching
+ # across all of them.
result = await session.execute(select(ReferenceType))
return list(result.scalars().all())
diff --git a/core/switch_core/migrations/versions/8b276792ee30_multi_tenancy_tenants_and_tenant_id.py b/core/switch_core/migrations/versions/8b276792ee30_multi_tenancy_tenants_and_tenant_id.py
index abced0f85..2df046182 100644
--- a/core/switch_core/migrations/versions/8b276792ee30_multi_tenancy_tenants_and_tenant_id.py
+++ b/core/switch_core/migrations/versions/8b276792ee30_multi_tenancy_tenants_and_tenant_id.py
@@ -19,13 +19,12 @@ Order:
`users.role = 'admin'`, `member` otherwise.
4. Add `tenant_id` to every scoped table as `NOT NULL DEFAULT '<zero>'`, then
drop the default. Since Postgres 11, adding a column with a constant
- default is a metadata-only change — no rewrite, no table lock beyond
- `ACCESS EXCLUSIVE` for the instant it takes to update the catalog. The
- alternative sequence (nullable, backfill every row, then `SET NOT NULL`)
- is what the spike proposed and is not needed here: there is only one
- tenant to backfill to, the same constant for every row, so a computed
- backfill buys nothing and would rewrite `messages` and `media_blobs`
- (20MB rows) under an exclusive lock instead.
+ default is a metadata-only change — no rewrite. The alternative sequence
+ (nullable, backfill every row, then `SET NOT NULL`) is what the spike
+ proposed and is not needed here: there is only one tenant to backfill to,
+ the same constant for every row, so a computed backfill buys nothing and
+ would rewrite `messages` and `media_blobs` (20MB rows) instead of just
+ touching the catalog.
5. Add the foreign key to `tenants`, and `UNIQUE (id, tenant_id)` on the
tables actually referenced by a composite key.
6. Swap the uniqueness constraints that were global singletons and are not
@@ -34,12 +33,27 @@ Order:
default-bridge partial index.
7. Rewrite every scoped-to-scoped foreign key as composite: drop the old
single-column constraint, add the new one `NOT VALID`, then `VALIDATE
- CONSTRAINT` — so the validation scan takes a lock no stronger than a
- plain read for the duration of the scan, rather than blocking writes for
- as long as the scan takes. Five keys use the Postgres 15+ column-list
- `ON DELETE SET NULL (<col>)` form: a plain multi-column `SET NULL` would
- null every referencing column including `tenant_id`, which then fails
- the new NOT NULL constraint on the very delete this is meant to allow.
+ CONSTRAINT`. Five keys use the Postgres 15+ column-list `ON DELETE SET
+ NULL (<col>)` form: a plain multi-column `SET NULL` would null every
+ referencing column including `tenant_id`, which then fails the new NOT
+ NULL constraint on the very delete this is meant to allow.
+
+**On locking: this whole revision runs inside one transaction** —
+`migrations/env.py` wraps every revision in `context.begin_transaction()`,
+and this one adds no `autocommit_block` of its own. Every `ACCESS EXCLUSIVE`
+lock taken by any statement above — including the plain `CREATE UNIQUE INDEX`
+built for each `UNIQUE (id, tenant_id)` and for the uniqueness swaps in step
+6 — is held on its table until the whole migration commits, not just for the
+instant that statement runs. The `NOT VALID` / `VALIDATE CONSTRAINT` split in
+step 7 buys nothing here: a single transaction holds the lock from the first
+statement to the commit regardless of when the validating scan runs, and
+`VALIDATE CONSTRAINT` cannot run in a later, separate transaction unless the
+`NOT VALID` addition already committed. It stays anyway, commented, because
+it becomes useful the day this migration is split so the addition and the
+validation are in different transactions — see the note on `CONCURRENTLY`
+below in the design doc if that split is needed. The longest-held lock here
+is whichever unique index build takes the longest, most likely the ones on
+`messages` and `media_blobs`.
This migration creates no roles, issues no grants, and adds no row-level
security policy — that is a separate, later change (see the design doc's
@@ -728,7 +742,11 @@ def upgrade() -> None:
postgresql_where=sa.text("is_default"),
)
- # 7. Rewrite every scoped-to-scoped FK as composite.
+ # 7. Rewrite every scoped-to-scoped FK as composite. `NOT VALID` then
+ # `VALIDATE CONSTRAINT` buys no lock reduction while the whole revision
+ # runs in one transaction (see the module docstring) — it stays because
+ # it is what makes the pair splittable across two transactions later,
+ # which is the only way this split ever pays for itself.
for (
table,
old_name,
diff --git a/core/tests/conftest.py b/core/tests/conftest.py
index 305d40bd7..d759fbf0d 100644
--- a/core/tests/conftest.py
+++ b/core/tests/conftest.py
@@ -28,7 +28,7 @@ async def _seed_tenant_zero(conn: AsyncConnection) -> None:
"""
await conn.execute(
insert(Tenant.__table__).values(
- id=TENANT_ZERO_ID, slug="default", name="Tenant Zero"
+ id=TENANT_ZERO_ID, slug="default", name="Default"
)
)
diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.py
index 9bad5e68b..d1bb41e6d 100644
--- a/core/tests/integration/conftest.py
+++ b/core/tests/integration/conftest.py
@@ -319,7 +319,7 @@ async def _seed_tenant_zero(engine: AsyncEngine) -> None:
async with engine.begin() as conn:
await conn.execute(
insert(Tenant.__table__).values(
- id=TENANT_ZERO_ID, slug="default", name="Tenant Zero"
+ id=TENANT_ZERO_ID, slug="default", name="Default"
)
)
diff --git a/core/tests/switch_core/db/test_multi_tenant_scoping.py b/core/tests/switch_core/db/test_multi_tenant_scoping.py
new file mode 100644
index 000000000..80b57b237
--- /dev/null
+++ b/core/tests/switch_core/db/test_multi_tenant_scoping.py
@@ -0,0 +1,390 @@
+"""Two-tenant behaviour for the multi-tenancy Phase 1 schema (CHOO-2623).
+
+Every fixture in the rest of the suite runs against a single tenant (tenant
+zero), so none of it can tell a composite foreign key from a single-column
+one, or a per-tenant unique constraint from a global one — the two schemas
+behave identically until a second tenant exists. These tests are the ones
+that actually create one.
+"""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import delete
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import (
+ Agent,
+ ApiKey,
+ Client,
+ CollaborationBridge,
+ Document,
+ ReferenceType,
+ Room,
+ RoomGroup,
+ Tenant,
+ User,
+)
+
+TENANT_A = "tenant-a"
+TENANT_B = "tenant-b"
+
+
+async def _make_tenant(session: AsyncSession, tenant_id: str) -> Tenant:
+ tenant = Tenant(id=tenant_id, slug=tenant_id, name=tenant_id)
+ session.add(tenant)
+ await session.flush()
+ return tenant
+
+
+async def _make_user(session: AsyncSession, name: str) -> User:
+ user = User(name=name, email=f"{name}@example.invalid", role="user")
+ session.add(user)
+ await session.flush()
+ return user
+
+
+async def _make_client(
+ session: AsyncSession, tenant_id: str, matrix_user_id: str
+) -> Client:
+ client = Client(
+ tenant_id=tenant_id,
+ matrix_user_id=matrix_user_id,
+ display_name=matrix_user_id,
+ type="agent",
+ )
+ session.add(client)
+ await session.flush()
+ return client
+
+
+async def _make_api_key(
+ session: AsyncSession, tenant_id: str, user_id: str, label: str
+) -> ApiKey:
+ api_key = ApiKey(
+ tenant_id=tenant_id,
+ user_id=user_id,
+ key_hash=f"hash-{tenant_id}-{label}",
+ encrypted_key="enc",
+ label=label,
+ type="agent",
+ )
+ session.add(api_key)
+ await session.flush()
+ return api_key
+
+
+async def _make_agent(
+ session: AsyncSession,
+ tenant_id: str,
+ name: str,
+ owner_id: str,
+ *,
+ parent_agent_id: str | None = None,
+) -> Agent:
+ client = await _make_client(session, tenant_id, f"@{tenant_id}-{name}:test")
+ api_key = await _make_api_key(session, tenant_id, owner_id, name)
+ agent = Agent(
+ tenant_id=tenant_id,
+ name=name,
+ description=f"{name} desc",
+ agent_type="always_on",
+ connector_type="claude_code",
+ integration_profile={"connection_model": "always_on"},
+ client_id=client.id,
+ api_key_id=api_key.id,
+ owner_id=owner_id,
+ parent_agent_id=parent_agent_id,
+ )
+ session.add(agent)
+ await session.flush()
+ return agent
+
+
+class TestCrossTenantForeignKeyRejected:
+ async def test_child_row_disagreeing_with_parent_tenant_is_rejected(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """An agent in tenant B naming a client that actually belongs to
+ tenant A must fail at the database, via `fk_agents_client` — the
+ composite key is the thing that makes this unrepresentable, not
+ application code that happens to always pass matching ids."""
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+ owner = await _make_user(session, "cross-tenant-owner")
+ client_in_a = await _make_client(session, tenant_a.id, "@mismatch:test")
+ api_key_in_b = await _make_api_key(
+ session, tenant_b.id, owner.id, "mismatched"
+ )
+ await session.commit()
+
+ mismatched_agent = Agent(
+ tenant_id=tenant_b.id,
+ name="mismatched",
+ description="disagrees with its own client's tenant",
+ agent_type="always_on",
+ connector_type="claude_code",
+ integration_profile={"connection_model": "always_on"},
+ client_id=client_in_a.id,
+ api_key_id=api_key_in_b.id,
+ owner_id=owner.id,
+ )
+ session.add(mismatched_agent)
+ with pytest.raises(IntegrityError):
+ await session.flush()
+
+
+class TestPerTenantUniqueness:
+ async def test_same_agent_name_in_two_tenants(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+ owner = await _make_user(session, "reviewer-owner")
+
+ agent_a = await _make_agent(session, tenant_a.id, "reviewer", owner.id)
+ agent_b = await _make_agent(session, tenant_b.id, "reviewer", owner.id)
+ await session.commit()
+
+ assert agent_a.id != agent_b.id
+ assert agent_a.name == agent_b.name == "reviewer"
+
+ async def test_same_matrix_user_id_in_two_tenants(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+
+ client_a = await _make_client(session, tenant_a.id, "@shared:test")
+ client_b = await _make_client(session, tenant_b.id, "@shared:test")
+ await session.commit()
+
+ assert client_a.id != client_b.id
+ assert client_a.matrix_user_id == client_b.matrix_user_id == "@shared:test"
+
+ async def test_same_matrix_room_id_in_two_tenants(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+
+ room_a = Room(
+ tenant_id=tenant_a.id,
+ matrix_room_id="!shared:test",
+ name="room",
+ description="room desc",
+ )
+ room_b = Room(
+ tenant_id=tenant_b.id,
+ matrix_room_id="!shared:test",
+ name="room",
+ description="room desc",
+ )
+ session.add_all([room_a, room_b])
+ await session.commit()
+
+ assert room_a.id != room_b.id
+ assert room_a.matrix_room_id == room_b.matrix_room_id == "!shared:test"
+
+ async def test_each_tenant_can_have_its_own_default_bridge(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+ client_a = await _make_client(session, tenant_a.id, "@bridge-a:test")
+ client_b = await _make_client(session, tenant_b.id, "@bridge-b:test")
+
+ bridge_a = CollaborationBridge(
+ tenant_id=tenant_a.id,
+ type="slack",
+ display_name="Bridge A",
+ client_id=client_a.id,
+ status="active",
+ is_default=True,
+ )
+ bridge_b = CollaborationBridge(
+ tenant_id=tenant_b.id,
+ type="slack",
+ display_name="Bridge B",
+ client_id=client_b.id,
+ status="active",
+ is_default=True,
+ )
+ session.add_all([bridge_a, bridge_b])
+ await session.commit()
+
+ assert bridge_a.is_default is True
+ assert bridge_b.is_default is True
+
+ async def test_second_default_bridge_in_same_tenant_still_rejected(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The partial unique index is per-tenant now, not gone: two defaults
+ in the *same* tenant must still collide."""
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ client_1 = await _make_client(session, tenant_a.id, "@bridge-1:test")
+ client_2 = await _make_client(session, tenant_a.id, "@bridge-2:test")
+
+ first = CollaborationBridge(
+ tenant_id=tenant_a.id,
+ type="slack",
+ display_name="First",
+ client_id=client_1.id,
+ status="active",
+ is_default=True,
+ )
+ session.add(first)
+ await session.commit()
+
+ second = CollaborationBridge(
+ tenant_id=tenant_a.id,
+ type="slack",
+ display_name="Second",
+ client_id=client_2.id,
+ status="active",
+ is_default=True,
+ )
+ session.add(second)
+ with pytest.raises(IntegrityError):
+ await session.flush()
+
+ async def test_reference_types_accepts_same_slug_in_two_tenants(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant_a = await _make_tenant(session, TENANT_A)
+ tenant_b = await _make_tenant(session, TENANT_B)
+ owner = await _make_user(session, "reftype-owner")
+
+ type_a = ReferenceType(
+ tenant_id=tenant_a.id,
+ type="doc",
+ owner_id=owner.id,
+ read_visibility="private",
+ write_visibility="private",
+ display_name="Doc",
+ instructions="Use doc links.",
+ value_hint="Paste a URL.",
+ )
+ type_b = ReferenceType(
+ tenant_id=tenant_b.id,
+ type="doc",
+ owner_id=owner.id,
+ read_visibility="private",
+ write_visibility="private",
+ display_name="Doc",
+ instructions="Use doc links.",
+ value_hint="Paste a URL.",
+ )
+ session.add_all([type_a, type_b])
+ await session.commit()
+
+ assert type_a.tenant_id != type_b.tenant_id
+ assert type_a.type == type_b.type == "doc"
+
+
+class TestSetNullOnDeleteKeepsTenantIdIntact:
+ """`ON DELETE SET NULL (<col>)` names its column so the delete only nulls
+ that column, never `tenant_id` — a plain multi-column `SET NULL` would
+ null both and then fail the `NOT NULL` constraint on `tenant_id`, which
+ is exactly the bug this form exists to avoid (see the design doc's
+ "Composite foreign keys" section). These three keys have no other test
+ exercising the database's own `ON DELETE` behaviour directly: existing
+ coverage either goes through store methods that reparent explicitly
+ before deleting (room groups) or covers a different key (`rooms.group_id`,
+ `messages.sender_client_id`)."""
+
+ async def test_deleting_parent_agent_nulls_only_parent_agent_id(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant = await _make_tenant(session, TENANT_A)
+ tenant_id = tenant.id
+ owner = await _make_user(session, "set-null-agent-owner")
+ parent = await _make_agent(session, tenant_id, "parent-agent", owner.id)
+ child = await _make_agent(
+ session,
+ tenant_id,
+ "child-agent",
+ owner.id,
+ parent_agent_id=parent.id,
+ )
+ await session.commit()
+ child_id = child.id
+
+ await session.execute(delete(Agent).where(Agent.id == parent.id))
+ await session.commit()
+ session.expire_all()
+
+ refreshed = await session.get(Agent, child_id)
+ assert refreshed is not None
+ assert refreshed.parent_agent_id is None
+ assert refreshed.tenant_id == tenant_id
+
+ async def test_deleting_creator_agent_nulls_only_created_by_agent_id(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ tenant = await _make_tenant(session, TENANT_A)
+ tenant_id = tenant.id
+ owner = await _make_user(session, "set-null-doc-owner")
+ creator = await _make_agent(session, tenant_id, "creator-agent", owner.id)
+ document = Document(
+ tenant_id=tenant_id,
+ owner_id=owner.id,
+ room_id=None,
+ created_by_agent_id=creator.id,
+ read_visibility="private",
+ write_visibility="private",
+ name="doc",
+ description="doc desc",
+ instructions="doc instructions",
+ content="doc content",
+ )
+ session.add(document)
+ await session.commit()
+ document_id = document.id
+
+ await session.execute(delete(Agent).where(Agent.id == creator.id))
+ await session.commit()
+ session.expire_all()
+
+ refreshed = await session.get(Document, document_id)
+ assert refreshed is not None
+ assert refreshed.created_by_agent_id is None
+ assert refreshed.tenant_id == tenant_id
+
+ async def test_deleting_parent_group_nulls_only_parent_group_id(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Deletes the parent group directly (unlike `RoomGroupStore.delete`,
+ which reparents children first) so the FK's own `SET NULL` is what is
+ under test, not the store's promote-on-delete behaviour."""
+ async with session_factory() as session:
+ tenant = await _make_tenant(session, TENANT_A)
+ tenant_id = tenant.id
+ parent = RoomGroup(tenant_id=tenant_id, name="parent-group")
+ session.add(parent)
+ await session.flush()
+ child = RoomGroup(
+ tenant_id=tenant_id, name="child-group", parent_group_id=parent.id
+ )
+ session.add(child)
+ await session.commit()
+ child_id = child.id
+
+ await session.execute(delete(RoomGroup).where(RoomGroup.id == parent.id))
+ await session.commit()
+ session.expire_all()
+
+ refreshed = await session.get(RoomGroup, child_id)
+ assert refreshed is not None
+ assert refreshed.parent_group_id is None
+ assert refreshed.tenant_id == tenant_id
diff --git a/core/tests/switch_core/db/test_tenant_schema_catalogue.py b/core/tests/switch_core/db/test_tenant_schema_catalogue.py
new file mode 100644
index 000000000..a9f10ed56
--- /dev/null
+++ b/core/tests/switch_core/db/test_tenant_schema_catalogue.py
@@ -0,0 +1,147 @@
+"""Catalogue tests for the multi-tenancy Phase 1 schema (CHOO-2623).
+
+These read the built schema back out of the database — `pg_constraint` and
+friends, via SQLAlchemy's reflection `Inspector` — rather than the model
+source, so a table added later without following the tenant-scoping rule
+fails here even if nobody remembers to update these tests by hand. See
+`docs/old/multi-tenancy-phase1-db.md` for the rule itself:
+
+ Every table holding customer data carries a non-null `tenant_id`, and
+ every foreign key between two such tables carries `tenant_id` as well.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import inspect
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession, async_sessionmaker
+
+# Importing models registers every table (including the plain `Table()`
+# junction tables) on `Base.metadata`.
+import switch_core.db.models # noqa: F401
+from switch_core.db.base import Base
+
+
+def _scoped_tables() -> set[str]:
+ """Every table carrying a `tenant_id` column whose foreign key targets
+ `tenants.id` — the schema's own definition of "scoped".
+
+ Deliberately not the list from the design doc: a table that gains a
+ `tenant_id` later by copying the mixin (or the equivalent inline column,
+ for the plain `Table()` junction tables) is picked up automatically, and
+ one that forgets the foreign key to `tenants` is correctly left out and
+ so exempt from these checks — the accompanying test that every scoped
+ table's FKs carry `tenant_id` only means anything once a table is on this
+ list at all.
+ """
+ scoped = set()
+ for table in Base.metadata.tables.values():
+ tenant_id_col = table.columns.get("tenant_id")
+ if tenant_id_col is None:
+ continue
+ if any(
+ fk.column.table.name == "tenants" and fk.column.name == "id"
+ for fk in tenant_id_col.foreign_keys
+ ):
+ scoped.add(table.name)
+ return scoped
+
+
+def _get_foreign_keys(sync_conn, table_name: str) -> list[dict]:
+ return inspect(sync_conn).get_foreign_keys(table_name)
+
+
+def _get_unique_column_sets(sync_conn, table_name: str) -> list[frozenset[str]]:
+ insp = inspect(sync_conn)
+ sets = [
+ frozenset(uc["column_names"]) for uc in insp.get_unique_constraints(table_name)
+ ]
+ pk = insp.get_pk_constraint(table_name)
+ if pk.get("constrained_columns"):
+ sets.append(frozenset(pk["constrained_columns"]))
+ return sets
+
+
+async def _foreign_keys(conn: AsyncConnection, table_name: str) -> list[dict]:
+ return await conn.run_sync(_get_foreign_keys, table_name)
+
+
+async def _unique_column_sets(
+ conn: AsyncConnection, table_name: str
+) -> list[frozenset[str]]:
+ return await conn.run_sync(_get_unique_column_sets, table_name)
+
+
+class TestScopedTableCatalogue:
+ async def test_scoped_tables_exist_and_are_not_trivial(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Sanity check on the derivation itself: if this list ever collapses
+ to empty or to one table, the two tests below would pass vacuously."""
+ scoped = _scoped_tables()
+ assert len(scoped) >= 30, scoped
+ assert "messages" in scoped
+ assert "agents" in scoped
+ # Global tables must not appear.
+ assert "users" not in scoped
+ assert "oidc_identities" not in scoped
+ assert "feature_flags" not in scoped
+
+ async def test_every_cross_scoped_foreign_key_carries_tenant_id(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A foreign key from one scoped table to another must be composite
+ on `tenant_id`, so a row can never reference a parent in another
+ tenant. Foreign keys to a *global* table (e.g. `rooms.owner_id ->
+ users.id`) are single-column by design and are not checked here."""
+ scoped = _scoped_tables()
+ violations: list[tuple[str, str, str]] = []
+ async with session_factory() as session:
+ conn = await session.connection()
+ for table_name in scoped:
+ for fk in await _foreign_keys(conn, table_name):
+ ref_table = fk["referred_table"]
+ if ref_table not in scoped:
+ continue
+ local_cols = set(fk["constrained_columns"])
+ ref_cols = set(fk["referred_columns"])
+ if "tenant_id" not in local_cols or "tenant_id" not in ref_cols:
+ violations.append((table_name, fk["name"] or "?", ref_table))
+ assert violations == [], (
+ "foreign key(s) between scoped tables missing tenant_id "
+ f"(table, constraint, referenced table): {violations}"
+ )
+
+ async def test_every_referenced_scoped_table_has_id_tenant_unique(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Any scoped table that is the target of a composite (`tenant_id`,
+ `id`)-shaped foreign key must itself expose a `UNIQUE (id,
+ tenant_id)` — Postgres requires a unique constraint on the referenced
+ columns for a composite foreign key to exist at all, but this asserts
+ it is exactly the `(id, tenant_id)` shape the design calls for,
+ derived from who actually references whom rather than a hand-kept
+ list of "the ~13 referenced tables"."""
+ scoped = _scoped_tables()
+ async with session_factory() as session:
+ conn = await session.connection()
+ referenced: set[str] = set()
+ for table_name in scoped:
+ for fk in await _foreign_keys(conn, table_name):
+ ref_table = fk["referred_table"]
+ if ref_table not in scoped:
+ continue
+ local_cols = fk["constrained_columns"]
+ ref_cols = fk["referred_columns"]
+ if "tenant_id" in local_cols and "tenant_id" in ref_cols:
+ referenced.add(ref_table)
+
+ missing: list[str] = []
+ for table_name in referenced:
+ unique_sets = await _unique_column_sets(conn, table_name)
+ if not any({"id", "tenant_id"} <= s for s in unique_sets):
+ missing.append(table_name)
+ assert referenced, "expected at least one table referenced by a composite key"
+ assert missing == [], (
+ "scoped table(s) referenced by a composite key but missing "
+ f"UNIQUE (id, tenant_id): {missing}"
+ )
diff --git a/docs/old/multi-tenancy-phase1-db.md b/docs/old/multi-tenancy-phase1-db.md
index 8ebede246..0d7a1759b 100644
--- a/docs/old/multi-tenancy-phase1-db.md
+++ b/docs/old/multi-tenancy-phase1-db.md
@@ -1,11 +1,24 @@
# Multi-tenancy Phase 1: the database design
-Status: design, reviewed once. Implements §2 of `multi-tenancy.md` (spike
-CHOO-2603) for CHOO-2623. Not yet built.
-
-This document is the schema half of Phase 1: what tables change, what the
-policies look like, how a session learns which tenant it is acting for, and
-what the one migration does.
+Status: partially built. Implements §2 of `multi-tenancy.md` (spike CHOO-2603)
+for CHOO-2623.
+
+This document was written as one design covering the whole schema half of
+Phase 1 — new tables, per-tenant uniqueness, composite foreign keys, the
+row-level-security policies, and the session plumbing that sets the tenant —
+and its reasoning below still describes that whole shape. What actually
+shipped is narrower: **the tenant model, per-tenant uniqueness and the
+composite foreign keys are built**, in the one migration this document
+describes. **Row-level security is not**: `require_tenant_id()`, the policy
+attached to each table, `db/rls_ddl.py`, and the isolation test under "Done
+when" were all split out into a later change, along with everything in
+"Setting the tenant" and "The bootstrap problem" below — the `tenant_session`
+/ `system_session` seam, the 107-call-site and 206-call-site migrations off
+the raw session, and the request-side wiring. None of that exists in the
+codebase yet. Read the sections below as the design those later changes
+implement, not as a description of what is running today; "What Phase 1 does
+not close" has been updated to say which gaps are this migration's and which
+belong to the deferred work.
Postgres 16 everywhere — local Compose, the chart, and the test containers —
and two things below need at least 15, so that is a floor, not an incidental
@@ -397,20 +410,48 @@ One revision:
3. Insert a membership for every existing user — `owner` for accounts with the
global admin role, `member` otherwise.
4. Per scoped table: `add column tenant_id text not null default '<zero>'`,
- then drop the default. Since Postgres 11 that is a metadata-only operation;
- the add-nullable-then-backfill-then-set-not-null sequence the spike
- describes rewrites the whole table under an exclusive lock, which on
- `messages` and on `media_blobs` with its 20MB rows is the difference between
- a blink and an outage.
+ then drop the default. Since Postgres 11 that is a metadata-only operation
+ for *this one statement* — no table rewrite, unlike the
+ add-nullable-then-backfill-then-set-not-null sequence the spike describes,
+ which would rewrite `messages` and `media_blobs` (20MB rows) instead of
+ just touching the catalog.
5. Add the foreign key to `tenants` and, where the table is referenced, the
`unique (id, tenant_id)`.
6. Swap the uniqueness constraints listed above.
7. Rewrite each scoped-to-scoped foreign key as composite, `not valid` first
- and `validate constraint` after, so the validation scan does not hold an
- exclusive lock.
-8. Enable row-level security and create the policy on each table.
+ and `validate constraint` after.
No roles are created and no grants issued — see the role section above.
+Row-level security is not part of this migration either: `require_tenant_id()`,
+the policies and the isolation test described elsewhere in this document are
+deferred to a later change, tracked separately from the schema landed here
+(see "Status" at the top of this document).
+
+**On locking.** Alembic wraps a whole revision in one transaction
+(`migrations/env.py`, `context.begin_transaction()`), and this migration does
+not open an `autocommit_block` to opt out. So every `ACCESS EXCLUSIVE` lock
+taken above — including the plain `CREATE UNIQUE INDEX` behind step 5's
+`unique (id, tenant_id)` and step 6's uniqueness swaps — is held on its table
+for the whole migration, not released until it commits. The `not valid` /
+`validate constraint` split in step 7 does not reduce that: both statements
+run inside the same transaction, so the exclusive lock from the `not valid`
+add is already held by the time `validate constraint` runs its scan, and
+holding it is what a single transaction means. The split is retained anyway,
+commented at the call site, because it is the shape this migration would need
+if it were ever divided into two transactions — seconds without which
+dividing it later means rewriting the FK step, not just moving code. The
+longest single lock is very likely whichever unique index build takes
+longest — plausibly the ones on `messages` and `media_blobs`.
+
+If a rehearsal against a copy of the production database shows this is too
+slow to run as one migration, the fix is to move the index builds to `create
+unique index concurrently` inside an Alembic `autocommit_block`, each in its
+own non-transactional step. That drops the exclusive lock during the (much
+slower) concurrent build down to a share lock, at the cost of the migration
+no longer being atomic — a partial failure leaves indexes to clean up by hand
+rather than a rolled-back transaction. Deliberately not done here: there are
+no measurements yet showing it is needed, and atomicity is worth keeping
+until there are.
Only tenant zero exists when this runs, so the usual expand-then-contract
caution does not apply yet. From the next customer onward it does, and that
@@ -443,10 +484,12 @@ to prevent:
Named so they are decisions rather than omissions.
-- **The policies do not bite in a deployed environment.** The runtime still
- connects as a superuser, so every policy here is inert outside the test
- suite until the runtime-role work lands. Deliberate, and safe while one
- tenant exists — and the hard prerequisite for the second.
+- **No row-level security yet.** The migration that landed adds the tenant
+ model, per-tenant uniqueness and the composite foreign keys, and stops
+ there — `require_tenant_id()`, the policy, and the runtime-role work that
+ would make a policy bite are a later change, not merely inert code sitting
+ next to this one. Deliberate, and safe while one tenant exists — and the
+ hard prerequisite for the second.
- **Cross-tenant user enumeration.** `users` and `oidc_identities` have no
policy, so any tenant session can read every account. There is no exposure
while one tenant exists, and the correct fix needs invitations and a
@@ -460,6 +503,23 @@ Named so they are decisions rather than omissions.
- **No indexes on `tenant_id`.** With one tenant the column has no selectivity
and an index is pure write cost. Add them when the second tenant lands, in
one migration, `concurrently`, with data to measure against.
+- **Two references bypass the composite-key guarantee entirely, by being
+ plain strings rather than foreign keys.** `message_attachments.uri`
+ references `media_blobs.uri`, and `Reference.type` references
+ `reference_types.type`, and neither carries a `tenant_id` or a constraint of
+ any kind — so a row can be made to name another tenant's blob or reference
+ type, and nothing in this schema stops it. Row-level security closes this
+ once a session is tenant-scoped, because the lookup itself becomes
+ tenant-filtered rather than because the reference is checked; it does not
+ need a foreign key to be safe, but it is unsafe until that lands.
+- **Roughly ten read paths call `scalar_one_or_none()` on a column that is
+ now unique per tenant rather than globally**, so they raise
+ `MultipleResultsFound` the moment a second tenant has a row that also
+ matches — `agent_store.get_by_name`, `collaboration_bridge_store.get_default`,
+ `client_store.get_by_matrix_user_id`, and `room_store.get_by_matrix_room_id`
+ are four of them. They are correct today, with one tenant, and wrong the
+ day a second one exists; making the session tenant-scoped, in the next PR,
+ is what makes them correct rather than each needing its own fix.
- No plan, status or soft-delete on `tenants`; no tenant deletion; no
per-tenant feature flags; no tenant switching.
- No per-tenant agent registration credential — Phase 2 owns it as a security