All Docs
FeaturesCSI Teachable Replacement AppUpdated March 13, 2026

Multi-Tenant Organization Schema & Data Isolation

Multi-Tenant Organization Schema & Data Isolation

Overview

The platform is built on a multi-tenant architecture where every piece of data is strictly scoped to the organization it belongs to. This page explains how tenant isolation is modelled in the database and what guarantees it provides.

Core Concepts

Organizations as Tenants

An organization is the top-level entity in the platform. Every user, course, lesson, enrollment, and asset is owned by exactly one organization. Organizations are isolated from one another — no organization can read or modify another organization's data.

Organization ID as a Partition Key

Every table in the database includes an organization_id column that acts as a partition key. This column:

  • Links each row to its owning organization.
  • Is indexed to ensure efficient tenant-scoped queries.
  • Is enforced at the schema level, meaning rows cannot exist without a valid organization_id.
Example table structure (simplified):

courses
  id             uuid        PRIMARY KEY
  organization_id uuid       NOT NULL  -- tenant partition key
  title          text        NOT NULL
  created_at     timestamptz NOT NULL

Automatic Query Scoping

All queries and mutations issued against the database are automatically scoped to the authenticated tenant. This means:

  • Application code does not need to manually append WHERE organization_id = ? to every query.
  • The authenticated session carries the tenant context, and the data layer applies it transparently.
  • Attempting to access a resource that belongs to a different organization will return no results, not an error — the row simply does not exist from the perspective of the requesting tenant.

Data Isolation Guarantees

GuaranteeDescription
Read isolationA tenant can only read rows where organization_id matches their own.
Write isolationInserts and updates automatically stamp the authenticated tenant's organization_id.
Cross-tenant leak preventionSchema-level constraints and automatic scoping together prevent any path for cross-tenant data exposure.

Why This Matters

Multi-tenant isolation is the security foundation of the platform. By enforcing boundaries at the database schema level — rather than relying solely on application-layer checks — the system ensures that:

  • A misconfigured query cannot accidentally expose another tenant's courses or learner data.
  • New features that add tables or queries inherit the same isolation model automatically, as long as they include organization_id and use the scoped query layer.
  • Compliance and audit requirements around data separation are met by design.

Related Topics

  • Changelog — See what changed in each release.
  • Getting Started — How to provision a new organization.