Neon Multi Tenant

Neon Multi-Tenant Skill

When to Use

Invoke this skill when the task involves any of the following:

• Neon branch strategy for multi-tenant or multi-app isolation
• Schema organization across shared databases (e.g., shared auth + per-app schemas)
• Drizzle ORM configuration with tenant-scoped queries and automatic tenant_id injection
• Cloudflare Hyperdrive connection pooling for Neon in Workers
• Migration coordination across Neon branches
• Choosing isolation level: branches vs schemas vs RLS for different tenant tiers

This skill is Neon PostgreSQL-specific. For general multi-tenant architecture patterns, see multi-tenant-platform. For auth-specific patterns, see graduated-auth.

Core Concept: Neon Branches as Isolation Primitives

Neon's branch architecture maps naturally to multi-tenant isolation. A branch is a copy-on-write fork of the database at a point in time. Branches share storage for unchanged data, making them cost-effective for isolation.

production (default branch)
 |-- neon_auth schema (shared Better Auth tables)
 |-- platform schema (T0 management plane)
 |
 +-- app-alpha-prod (branch)
 |    |-- app_alpha schema (T1 partner data)
 |    |-- neon_auth schema (inherited, read-only reference)
 |    |
 |    +-- app-alpha-dev (branch of app-alpha-prod)
 |         |-- development copy for safe iteration
 |
 +-- app-beta-prod (branch)
      |-- app_beta schema (T1 partner data)
      |-- neon_auth schema (inherited, read-only reference)
      |
      +-- app-beta-dev (branch of app-beta-prod)
           |-- development copy for safe iteration

Key properties:

• Copy-on-write: Branches are near-instant to create and share unchanged pages with the parent.
• Independent compute: Each branch can have its own compute endpoint, enabling per-tenant scaling.
• Schema inheritance: A child branch inherits the parent's schema at creation time. Auth tables in neon_auth are present on all branches.
• Instant reset: Dev branches can be reset to their parent's state without a full restore.

SyncUpSuite Branch Layout

The SyncUp monorepo uses a single Neon project (your-neon-project, ID: your-neon-project-id) with the following branch hierarchy:

production (default)
 |-- neon_auth schema (Better Auth: users, sessions, accounts, verifications)
 |
 +-- brandsyncup-prod (br-xxx-xxx-xxxxxxxx)
 |    |-- brandsyncup schema (brand collaboration data)
 |    +-- brandsyncup-dev (br-xxx-xxx-xxxxxxxx)
 |
 +-- legalsyncup-production (br-xxx-xxx-xxxxxxxx)
      |-- legalsyncup schema (legal compliance data)
      +-- legalsyncup-development (br-xxx-xxx-xxxxxxxx)

• Shared auth: All apps authenticate against neon_auth on the production branch. Session tokens are portable across apps.
• Isolated data: Each app's domain tables live in app-specific schemas on app-specific branches.
• Dev branches: Feature development and schema iteration happen on dev branches that can be reset from their parent.

Schema Organization

The Three Schema Tiers

Rules

1. Never put app data in neon_auth. That schema is owned by Better Auth and shared across all apps. Adding app-specific columns to auth tables creates coupling.

2. Always use explicit schema names. Never rely on search_path for multi-schema databases. In Drizzle, specify schema on every table definition.

3. Extensions go in public. PostgreSQL extensions (uuid-ossp, pgcrypto, etc.) should be created in the public schema on the production branch so they propagate to all child branches.

4. Every app table has tenant_id. Even within an app-specific schema on an app-specific branch, tables must include tenant_id for RLS. This is defense-in-depth: the branch provides infrastructure isolation, and tenant_id + RLS provides row-level isolation within that branch.

Isolation Decision Matrix

Use this matrix to decide which isolation mechanism to apply at each tier of the 3-tier model:

Decision Flow

Is this a platform-level concern (billing, partner management)?
  YES -> T0 separate project
  NO  -> Does this partner need strong isolation (regulatory, SLA, data residency)?
           YES -> T1 dedicated Neon branch
           NO  -> T1 shared branch with schema isolation
                  -> T2 always uses RLS within the branch

Hybrid Example: SyncUpSuite

SyncUpSuite currently operates with a simplified model:

• T0: Platform management is in the production (default) branch.
• T1: Each app (BrandSyncUp, LegalSyncUp) is a T1 partner with its own branch.
• T2: Within each app, customer organizations are isolated via tenant_id + RLS.

As the platform grows, a T1 partner (e.g., an enterprise customer running their own BrandSyncUp instance) could be given their own Neon branch forked from brandsyncup-prod.

Drizzle ORM Tenant Configuration

Tenant-Scoped Client

Every database query must execute within a tenant context. The pattern is:

1. Create a base Drizzle client connected to the correct branch.
2. Wrap it in a tenant-scoped factory that injects tenant_id into all queries.
3. Use Drizzle's $onQuery or middleware hooks for automatic injection.

See templates/drizzle-tenant.ts for the full implementation.

Key Patterns

// Executing a tenant-scoped query (context + query in one transaction)
const docs = await tenantQuery(connectionString, { tenantId, userId }, async (db) => {
  return db.select().from(documents); // RLS enforces tenant_id filter
});

// Inserts with automatic tenant_id injection
await db.insert(documents).values({ title: 'New Doc' }); // tenant_id injected

Connection Strategy

Hyperdrive Connection Pooling

Cloudflare Hyperdrive provides connection pooling at the edge, reducing cold-start connection overhead for Neon. This matters for Workers because:

• Each Worker invocation would otherwise create a new TCP + TLS connection to Neon.
• Neon's serverless driver uses WebSocket, but Hyperdrive uses persistent TCP connections from Cloudflare's network.
• Hyperdrive caches query results at the edge (configurable).

Performance Impact

Cost note: Neon's free tier supports this branch-based isolation model for development and early production. As tenant count grows, costs scale through connection pooling (Hyperdrive) and storage, not through per-tenant database provisioning. Adding a T2 tenant is a row in the database and an RLS policy, not a new Neon branch.

See templates/hyperdrive-setup.md for configuration details.

Migration Patterns

Schema Changes Across Branches

Neon branches are point-in-time forks. Schema changes on a parent do NOT automatically propagate to existing child branches. This requires a deliberate migration strategy:

1. Apply to parent first. Run Drizzle migrations on the production (or app-prod) branch.
2. Reset dev branches. After parent migration, reset dev branches to inherit the new schema: neon branches reset <dev-branch-id> --parent.
3. Or migrate dev independently. For in-progress features, apply the same migration to the dev branch directly.

Shared Auth Schema Migrations

Changes to neon_auth tables affect all apps. The coordination protocol:

1. Draft the migration in a feature branch.
2. Review with all app teams (BrandSyncUp + LegalSyncUp).
3. Apply to production (default) branch during a maintenance window.
4. Reset or migrate all app branches.
5. Verify auth flows in all apps.

Drizzle Migration Commands

# Generate migration from schema changes
npx drizzle-kit generate

# Push schema directly (dev only, no migration files)
npx drizzle-kit push

# Apply migrations (production)
npx drizzle-kit migrate

# Open Drizzle Studio for visual inspection
npx drizzle-kit studio

Neon API for Branch Management

Branch lifecycle operations use the @neondatabase/api client:

import { createApiClient } from '@neondatabase/api';

const neon = createApiClient({ apiKey: process.env.NEON_API_KEY });

// Create a new branch for a T1 partner
const branch = await neon.createProjectBranch(projectId, {
  branch: {
    name: `partner-${partnerId}-prod`,
    parent_id: productionBranchId,
  },
  endpoints: [{ type: 'read_write' }],
});

// Reset a dev branch to match its parent
await neon.restoreProjectBranch(projectId, devBranchId, {
  source_branch_id: parentBranchId,
});

See templates/branch-strategy.sql for full examples.

Non-Negotiable Rules

1. Every query runs in tenant context. No database query executes without an explicit tenant_id binding, whether via Drizzle middleware, RLS SET variable, or explicit WHERE clause.

2. Auth tables are read-only from app branches. Apps read from neon_auth but never write directly. All auth mutations go through Better Auth's API on the production branch connection.

3. Dev branches are ephemeral. Never store data on dev branches that cannot be recreated. Dev branches can be reset at any time.

4. Connection strings are secrets. Never hardcode Neon connection strings. Use Doppler for injection and Hyperdrive bindings in production.

5. Migrations are forward-only. Never run DROP or destructive DDL without a rollback plan. Prefer additive migrations (add column, add table) over destructive ones.

6. Branch names are deterministic. Use the pattern <app>-<environment> (e.g., brandsyncup-prod, legalsyncup-development). For T1 partner branches, use <app>-partner-<id>-<env>.

Templates

References

Related Skills

• multi-tenant-platform -- General multi-tenant architecture, 3-tier model, governance rules
• graduated-auth -- Progressive authentication complexity with Better Auth
• theme-inspired-tokens -- Design token generation for multi-tenant theming