Multi-Tenancy in One Codebase

Every organizer on Stagedoor is a tenant. Their events, seat maps, orders, staff and API keys must be invisible to every other organizer, and all 340 of them share one database, one schema and one codebase. Nothing in the architecture separates them; the separation is a value, the organizer id, that has to be on every query that touches tenant data, every time, with no exception that is not written down. The security review found the query that listed events for the organizer dashboard took its organizer id from the request body, which means any organizer could ask for any other organizer's events by typing a different number.

This topic draws the tenant boundary in three places and shows what happens when one of them is missing. The tenant id lives on every tenant row. It travels in the request context, from the principal, never from the client. The repository cannot be called without it. And the database itself enforces it as the last line, with row-level security, so that the query which forgets the clause returns nothing rather than everything. The topic ends with the two cases the boundary must be crossed on purpose, and the three ways to lay tenants out, of which Stagedoor uses the cheapest.

Tenant on Every Row

events carries organizer_id directly. seats reach the tenant through event_id, orders through event_id, tickets through order_id and then the event, and api_keys carry organizer_id themselves. Every table either has a path to an organizer or is global: users is global, because a buyer is not owned by an organizer and buys from many. A table with no path to the tenant and no reason to be global is a design mistake, and the review found one, a venues table that had been added for one organizer and was readable by all.

async def list_events(repo: EventRepo, ctx: RequestContext) -> list[Event]:
    return await repo.list_for_tenant(ctx.tenant_id)
    # SELECT id, title, starts_at, status FROM events
    #  WHERE organizer_id = $1 ORDER BY starts_at

# the old handler, for contrast: the client named the tenant, and the query obliged
#   organizer_id = body["organizer_id"]

The domain function takes the request context of Chapter 4 and reads the tenant from it; the repository puts that value in the WHERE clause; nothing in the path looks at the request body. The old handler, in the comment, read the organizer id from the body, which is the client asking to be someone, and the query obliged. The difference is one line, and it is the entire tenant boundary at the application level: the tenant is a fact about the caller, established by the auth ring, and no request may name a different one.

Tenant in the Context

The auth ring of Chapter 4 resolves the principal, and for an organizer's owner, staff member or API key the principal has an organizer_id; the ring copies it into ctx.tenant_id when it builds the replacement context. For a buyer the tenant is empty, because a buyer's requests touch buyer-owned rows and public event listings, not tenant data. The storage layer reads the tenant from the context and from nowhere else. A request whose body or path names an organizer, GET /organizers/17/events, is asking a question, and the answer is the context's tenant or a 404: if 17 is the caller's organizer the request succeeds, and if it is not, the organizer does not exist as far as this caller is concerned, per the table in Topic 29.

The Repository Enforces It

Every storage function that reads or writes tenant data takes the tenant as a required, positional argument. list_for_tenant(tenant_id) exists; list_events() does not. The type checker rejects the call that forgets, in the editor, before a test runs. This is the same structural move as Topic 29's find_for_user: make the incorrect call impossible to write rather than easy to catch. The one storage function that reads across tenants, for the admin dashboard, is named list_all_tenants_events so that a code review of any call site sees the crossing in the function name, and it lives in a module that the linter of Chapter 4 allows only the admin package to import.

Row-Level Security as the Last Line

Application enforcement is necessary and it is one forgotten clause from a leak: a new report query, a raw SQL tool on the replica, a migration script that joins two tables and forgets the third. Postgres can enforce the boundary itself. Row-level security attaches a policy to a table, and every query against that table, from any code path, sees only the rows the policy admits. Stagedoor's policy admits rows whose organizer_id equals a setting on the connection, and the application sets that setting at the start of every transaction from the context's tenant.

ALTER TABLE events ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON events
    USING (organizer_id = nullif(current_setting('app.tenant_id', true), '')::bigint);
-- the second argument makes a missing setting NULL rather than an error;
-- NULL = anything is not true, so an unset tenant sees zero rows

-- in the application, at the top of every transaction that touches tenant data:
BEGIN;
SELECT set_config('app.tenant_id', $1, true);   -- true = local to this transaction (SET LOCAL)
SELECT id, title FROM events ORDER BY starts_at;    -- no WHERE, and still only this tenant's rows
COMMIT;                                            -- the setting is gone; the pooled connection is clean

The policy compares each row's organizer to the connection's setting, and the setting is read with a flag that returns NULL when it was never set, so a query on a connection with no tenant returns no rows rather than raising. The application sets the tenant with the local flag, which scopes the value to the current transaction: at commit or rollback it disappears, and the next request that borrows the same pooled connection starts with nothing set. The third statement has no WHERE at all, and it still returns only one tenant's events. That is the property: a query that forgets returns nothing, not everything. The policy applies to stagedoor_app because that role does not own the tables; the owner and superusers bypass policies unless the table is marked to force them, and the role that runs migrations owns the tables on purpose, so that the application role never does. The replica pg-replica-a enforces the same policies, so the report that runs there, and the analyst's raw SQL tool, see one organizer per transaction and cannot be talked into more.

Cross-Tenant Operations, Named

Three things in Stagedoor legitimately read across organizers: the admin dashboard, the nightly reconciliation of Chapter 10 that compares every organizer's payments with Payrail's ledger, and the aggregate metrics job. Each of them runs as an explicit all-tenants principal, connects through a second, smaller pool as the role stagedoor_ops, which carries the bypass attribute for row-level security, and logs every query it runs under a marker the audit dashboard filters on. The list of operations allowed to use that pool is a Python tuple of three names in one module, reviewed when it changes, and the pool refuses a caller whose operation is not in it.

What is not allowed is a cross-tenant job that runs as an ordinary principal with the tenant switched per iteration, or, worse, with the tenant unset and the WHERE clauses removed by hand. The first is a job that sees one organizer at a time and can be reasoned about; the second is the design in which the reconciliation ran with a tenant of the first organizer it looped over, saw one organizer's payments, reported 339 organizers as fully reconciled, and was believed for a month.

Shared vs Separate

One database, one schema, a tenant column and a policy per table is the cheapest layout: one migration per release, one connection pool, one backup, and isolation that is a policy rather than a process. Schema per tenant gives each organizer its own tables under one database, which isolates their rows structurally and turns every migration into 340 migrations, one of which will fail at 3 in the morning. Database per tenant is the strongest isolation, with separate backups, separate resource limits and separate everything, and it is the most operations by a factor of the tenant count. The tradeoff is isolation against operational multiplicity, and it is decided by a requirement that is written down, a contract that says an organizer's data must be physically separate, not by an assumption that separate feels safer. Stagedoor has no such contract, and stays with the column.