Guide

Multi-tenant applications

You can host many tenants on a single Layerbase database, and on Solo ($5/mo) that is often all you need. How you separate the tenants matters, though: one approach is covered by backups and one is not. This page explains which is which.

The short version

What one Layerbase database is

When you create a database, we provision an isolated instance of the engine and one database inside it, and we record that name. That recorded name is the unit for everything the platform does on your behalf: scheduled backups, restores, exports, branch creation, moving you between servers, and waking a hibernated database. Your plan's database count is a count of these instances.

Schema per tenant (PostgreSQL)

Connect with the credentials from your dashboard and create a schema per tenant:

CREATE SCHEMA tenant_acme;
CREATE SCHEMA tenant_globex;

CREATE TABLE tenant_acme.users (id bigserial PRIMARY KEY, email text);
CREATE TABLE tenant_globex.users (id bigserial PRIMARY KEY, email text);

Set search_path per connection or per request to scope queries to one tenant. Because all of this lives inside the provisioned database, a backup captures every tenant, a restore brings every tenant back, and a branch gives you a full copy of all of them to test against.

Extra logical databases, and why we do not recommend them

Nothing stops you from running CREATE DATABASE tenant_b; inside your instance, and it will work: it is reachable on the same host and port, and its storage counts toward your plan's allowance like everything else. What it does not get is coverage.

Scheduled and manual backups dump the database we provisioned, by name. A database you created yourself is not in that dump. Several routine operations rebuild your instance from that dump, and they recreate only the provisioned database:

• Restoring a backup rolls the provisioned database back and leaves your extra databases untouched, so the two end up at different points in time.
• Moving your database to another server re-provisions it from a backup. Extra databases do not survive the move.
• Restoring an archived or offloaded database rebuilds it from the retained backup. Extra databases do not survive it.

Branching is the exception that makes this easy to misread: a branch copies the whole data directory, so extra databases do appear on the branch. That is a copy, not a backup, and the branch's own backups have the same per-database scope. Do not take a working branch as evidence that the data is protected.

If you need hard separation between tenants rather than schema separation, create a second Layerbase database instead. That gives each tenant its own instance, its own credentials, and its own backups.

MySQL and MariaDB

In MySQL and MariaDB, a schema and a database are the same thing, so the schema-per-tenant pattern above is not available. Separate tenants inside the provisioned database with a table prefix or a tenant id column, or give each tenant its own Layerbase database. The same warning applies: CREATE DATABASE succeeds, and the result is outside your backups.

Redis and Valkey

Redis and Valkey work differently and need no warning. Your instance has 16 logical databases (0 to 15), your connection string puts you on database 0, and SELECT n switches between them. Backups snapshot the whole instance, so every logical database is captured and restored together. Using them to separate tenants or environments is safe.

Storage and your plan

Storage is measured across your whole instance, so tenants add up whichever pattern you choose. Your plan's database count, by contrast, counts instances: schemas and tenants inside one database do not consume a slot, and neither do branches.