Tenant

Multi-Tenant Architecture Schema

Defines the schema for managing multi-tenant architecture with:

Global control plane: Single database for auth, org management, tenant registry
Tenant data plane: Isolated databases per organization (UUID-based naming)

Design decisions:

Database naming: {uuid}.turso.io (not org-slug, since slugs can be modified)
Each tenant has its own Turso database for complete data isolation
Global database stores user auth, organizations, and tenant metadata

Source: packages/spec/src/cloud/tenant.zod.ts

TypeScript Usage

import { PackageInstallation, PackageInstallationStatus, ProvisionTenantRequest, ProvisionTenantResponse, TenantContext, TenantDatabase, TenantDatabaseStatus, TenantIdentificationSource, TenantRoutingConfig } from '@objectstack/spec/cloud';
import type { PackageInstallation, PackageInstallationStatus, ProvisionTenantRequest, ProvisionTenantResponse, TenantContext, TenantDatabase, TenantDatabaseStatus, TenantIdentificationSource, TenantRoutingConfig } from '@objectstack/spec/cloud';

// Validate data
const result = PackageInstallation.parse(data);

PackageInstallation

Properties

Property	Type	Required	Description
id	`string`	✅	Unique installation identifier
tenantId	`string`	✅	Tenant database ID
packageId	`string`	✅	Package identifier
version	`string`	✅	Installed package version
status	`Enum<'installing' \| 'active' \| 'disabled' \| 'uninstalling' \| 'failed'>`	✅	Installation status
installedAt	`string`	✅	Installation timestamp
installedBy	`string`	✅	User ID who installed the package
config	`Record<string, any>`	optional	Package-specific configuration
updatedAt	`string`	✅	Last update timestamp

PackageInstallationStatus

Allowed Values

installing
active
disabled
uninstalling
failed

ProvisionTenantRequest

Properties

Property	Type	Required	Description
organizationId	`string`	✅	Organization ID
region	`string`	optional	Deployment region preference
plan	`Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>`	✅	Tenant plan tier
storageLimitMb	`integer`	optional	Storage limit in megabytes
metadata	`Record<string, any>`	optional	Custom tenant metadata

ProvisionTenantResponse

Properties

Property	Type	Required	Description
tenant	`Object`	✅	Provisioned tenant database
durationMs	`number`	✅	Provisioning duration in milliseconds
warnings	`string[]`	optional	Provisioning warnings

TenantContext

Properties

Property	Type	Required	Description
tenantId	`string`	✅	Current tenant database ID
organizationId	`string`	✅	Current organization ID
organizationSlug	`string`	optional	Organization slug
databaseUrl	`string`	✅	Tenant database URL
plan	`Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>`	✅	Tenant plan tier
metadata	`Record<string, any>`	optional	Custom tenant metadata

TenantDatabase

Properties

Property	Type	Required	Description
id	`string`	✅	Unique tenant database identifier (UUID)
organizationId	`string`	✅	Organization ID (foreign key to sys_organization)
databaseName	`string`	✅	Database name (UUID-based)
databaseUrl	`string`	✅	Full database URL
authToken	`string`	✅	Encrypted tenant-specific auth token
status	`Enum<'provisioning' \| 'active' \| 'suspended' \| 'archived' \| 'failed'>`	✅	Database status
region	`string`	✅	Deployment region
plan	`Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>`	✅	Tenant plan tier
storageLimitMb	`integer`	✅	Storage limit in megabytes
createdAt	`string`	✅	Database creation timestamp
updatedAt	`string`	✅	Last update timestamp
lastAccessedAt	`string`	optional	Last accessed timestamp
metadata	`Record<string, any>`	optional	Custom tenant configuration

TenantDatabaseStatus

Allowed Values

provisioning
active
suspended
archived
failed

TenantIdentificationSource

Allowed Values

subdomain
custom_domain
header
jwt_claim
session
default

TenantRoutingConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable multi-tenant mode
identificationSources	`Enum<'subdomain' \| 'custom_domain' \| 'header' \| 'jwt_claim' \| 'session' \| 'default'>[]`	✅	Tenant identification strategy (in order of precedence)
defaultTenantId	`string`	optional	Default tenant ID
subdomainPattern	`string`	optional	Subdomain pattern for tenant extraction
customDomainMapping	`Record<string, string>`	optional	Custom domain to tenant ID mapping
tenantHeaderName	`string`	✅	Header name for tenant ID
jwtOrganizationClaim	`string`	✅	JWT claim name for organization ID

On this page