---
title: "Multi-Tenancy"
description: "Build SaaS applications on HeliosDB Lite with tenant isolation, quotas, change data capture and row-level security."
---

# Multi-Tenancy

Build SaaS applications with built-in tenant isolation, quotas, and change data capture.

## Tenant Management

### Create Tenant

```bash
\tenant create acme_corp enterprise schema
```

### List Tenants

```bash
\tenants
```

### Switch Tenant Context

```bash
\tenant use acme_corp
```

## Isolation Levels

| Level | Description |
|-------|-------------|
| `shared` | Logical isolation via tenant_id column |
| `schema` | Per-tenant schema isolation |
| `database` | Full database isolation |

## Quotas

### Set Quotas

```bash
\tenant quota set acme storage=10GB connections=50 qps=1000
```

### View Usage

```bash
\tenant usage acme
```

## Plans

```bash
\tenant plans                    # List plans
\tenant plan create pro tier=2 storage=50GB
\tenant plan acme_corp pro       # Assign plan
```

## Change Data Capture (CDC)

```bash
\tenant cdc                      # View recent events
\tenant cdc export events.json   # Export to file
```

## Isolation over the Network

Row-level security policies apply to PostgreSQL wire sessions and to REST requests. A REST request runs as the database role named in its token's `sub` claim. Give each tenant its own role, write policies against `current_user`, and never issue tenant tokens for superusers, who bypass row-level security. See the [multi-tenant example](https://www.heliosdb.com/docs/lite/website/examples/readme/#multi-tenant-saas).

REST endpoints for tenant management are planned. Until then, manage tenants with the REPL commands above.

## Related

- [Row-Level Security](https://www.heliosdb.com/docs/lite/features/rls/): policy-based access control
- [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/): roles and REST tokens