SaasForgeKit Docs

Appearance

Tenancy Mode (Required First Step) ​

Before installing SaasForgeKit, you must choose your tenancy database mode.

This decision affects how tenant data is stored and how migrations are executed. Set it first in your .env file, then continue with macOS, Windows, or Docker installation.

Available Modes ​

single_db (default) ​

All tenants share one database. Tenant data is isolated using tenant_id columns.

Use this when:

  • You want the simplest local setup.
  • You are launching quickly with minimal database complexity.
  • You do not need separate databases per tenant.

multi_db ​

Each tenant gets its own database, while central tables (users, plans, app settings, etc.) remain in the central database.

Use this when:

  • You need strict tenant-level database isolation.
  • Your infrastructure is prepared to create/manage tenant databases.
  • You require per-tenant database operations (backup, restore, compliance boundaries).

multi_db database privileges (important) ​

When using TENANCY_DB_MODE=multi_db, SaasForgeKit must create/manage tenant databases at runtime. Your database user therefore needs elevated privileges beyond normal CRUD access.

For MySQL/MariaDB, the DB user typically needs permission to:

  • Create databases
  • Drop databases (or at least manage lifecycle if you support tenant removal)
  • Create/alter/drop tables and indexes in tenant databases
  • Create/alter/drop views, triggers, and routines if your schema uses them

A common setup is to grant broad privileges on tenant-prefixed databases (for example tenant%).

Example (adjust username/host/password to your environment):

sql
CREATE USER 'saasforgekit'@'%' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON `tenant%`.* TO 'saasforgekit'@'%';
GRANT ALL PRIVILEGES ON `saasforgekit_central`.* TO 'saasforgekit'@'%';
FLUSH PRIVILEGES;

If your security policy requires tighter permissions, ask your DBA to grant the minimum set required for database creation and tenant schema management.

Configure Tenancy Mode ​

Open .env and set:

env
TENANCY_DB_MODE=single_db

Or:

env
TENANCY_DB_MODE=multi_db

Important Notes ​

  • Set TENANCY_DB_MODE before running migrations.
  • If you switch modes later, treat it as a migration task (schema/data strategy may differ).
  • For most local development, start with single_db.
  • Many shared-hosting plans do not allow database-level create/drop privileges. In that case, use single_db.

Next Step ​

Continue with your platform guide: