Schema-Based Sharding User Guide

Overview

Schema-based sharding distributes data across nodes based on schema/tenant, enabling perfect data isolation and independent scaling per tenant.

Benefits

Tenant isolation
Independent scaling per schema
Simple data locality
Compliance-friendly

Configuration

sharding:
  strategy: schema_based
  schemas:
    tenant_a: node-1
    tenant_b: node-2
    tenant_c: node-3

SQL Examples

-- Create sharded database
CREATE DATABASE myapp WITH (sharding = 'schema_based');

-- Create tenant schemas
CREATE SCHEMA tenant_123;
CREATE SCHEMA tenant_456;

-- Assign to nodes
SELECT heliosdb.assign_schema('tenant_123', 'node-1');
SELECT heliosdb.assign_schema('tenant_456', 'node-2');

-- Query automatically routes to correct node
SET search_path = tenant_123;
SELECT * FROM users;  -- Executes on node-1

Use Cases

SaaS Multi-Tenancy

-- Each customer gets dedicated schema
CREATE SCHEMA customer_acme;
CREATE SCHEMA customer_globex;

-- Data isolation guaranteed
SET search_path = customer_acme;
-- All queries operate only on customer_acme data

Geographic Sharding

-- Schema per region
CREATE SCHEMA us_east;
CREATE SCHEMA eu_west;

SELECT heliosdb.assign_schema('us_east', 'us-east-1-node');
SELECT heliosdb.assign_schema('eu_west', 'eu-west-1-node');

Best Practices

Plan schema distribution carefully
Monitor per-schema resource usage
Rebalance as tenants grow
Use with row-level security

For more: /docs/architecture/schema-sharding.md