Multi-tenancy and catalog sharing

BoilStream isolates each tenant by default and permits access across tenants only through an explicit membership or catalog grant.

Isolation by default

Each tenant has its own:

• managed DuckLake catalogs, including tenant-specific duckie and boil__stream defaults when automatic provisioning is enabled;
• encrypted non-catalog secrets;
• server-side filesystem scope; and
• authenticated sessions and resource limits.

Two tenants may use the same catalog display name without referring to the same catalog. The canonical catalog UUID, not the display name, identifies the authorization and storage target.

Sharing one catalog

Sharing reuses the owner's catalog. It does not copy data into the requester's tenant or create a second physical catalog.

Blue boxes are authenticated requesters, purple boxes are authorization decisions, and the green box is the catalog they share. Sharing does not create another copy of the data.

Concept	Meaning
Requester	The authenticated user whose access is checked and audited
Storage owner	The tenant that owns the catalog and its data
Catalog UUID	The authoritative identity selected for the operation
Display name	A tenant-visible presentation name that may be reused elsewhere
Access mode	The operations allowed for this requester on this catalog

The requester cannot change the storage owner by choosing a different SQL alias, database name, or same-named local catalog.

How access is obtained

Catalog access may come from:

• ownership, which provides administrative catalog access;
• active tenant membership, which currently provides admin access to catalogs owned by that tenant; or
• a direct catalog grant, which carries an explicit mode and may expire.

Removing membership or revoking, reducing or expiring a grant can invalidate existing access. Applications must handle authorization failures and request fresh credentials when authorized; a previously issued credential does not preserve a revoked grant.

Catalog access modes

Catalog modes are intentionally separate from product roles:

Mode	Data reads	Data mutations	Catalog DDL
reader	yes	no	no
writer	yes	yes	no
admin	yes	yes	yes

Catalog ownership, membership, and grant lifecycle remain BoilStream control-plane operations; the admin data-plane mode does not let a SQL statement rewrite those relationships.

Product roles and catalog access modes serve different purposes. Check the user's catalog permissions when an operation is denied; a successful web login alone does not grant access to every catalog.

Managed DuckDB clients

The public BoilStream extension authenticates to BoilStream and attaches a catalog by UUID under a local alias. The extension handles short-lived credentials and the server connection. Applications do not need catalog object-storage credentials.

INSTALL boilstream FROM community;
LOAD boilstream;

PRAGMA boilstream_bootstrap_session(
    'https://your-server.example/secrets:<bootstrap-token>');

FROM boilstream_ducklakes();
PRAGMA boilstream_attach_ducklake(
    '9a927d1b-30f5-48da-91eb-af1492bf31c0',
    'shared_analytics');

SELECT * FROM shared_analytics.main.events;

Use the UUID returned by boilstream_ducklakes(). The local alias is for SQL convenience and has no authorization meaning.

Other tenant-scoped resources

Non-catalog secrets remain encrypted and scoped to the authenticated tenant. Server-side filesystem access is confined below the configured tenant data base path. Session and connection limits are deployment settings; use the generated configuration reference rather than copying partial security configuration.

Related guides

• DuckLake — defaults, streaming catalogs, attach, and hydration
• Authentication — login and identity-provider options
• Cluster mode — availability and recovery boundaries
• Reliability guarantees — fail-closed and durability behavior