Customizing databases

Note

It’s recommended to read the Multi-database tenancy and DatabaseTenancyBootstrapper pages of the documentation first.

This page is fairly low-level so don’t worry if some things feel confusing or complex at first. You do not need to understand everything here before you can start using multi-database tenancy. You only need the information on this page if you want to customize tenant databases in some way.

That said, for curious readers this page may still be interesting on its own, since it explains what’s actually happening under the hood with database connections when using multi-database tenancy.

You can customize most parts of the tenant connection by setting tenancy_db_* keys on a tenant. For instance:

Tenant::create(['tenancy_db_name' => 'foo']);

will create a database called foo, and every time this tenant is used, that database will be what the tenant connection connects to.

If you do not specify a database name, it is by default¹ created by combining tenant + $tenant->id:

php artisan tinker

> $tenant = App\Models\Tenant::create();
= App\Models\Tenant {#5941
    data: null,
    id: "b37609c7-035c-4a68-aff5-ac60ff334699",
    updated_at: "2025-09-26 12:29:39",
    created_at: "2025-09-26 12:29:39",
    tenancy_db_name: "tenantb37609c7-035c-4a68-aff5-ac60ff334699",
  }

Security

Critically, you MUST never derive database names from user input. When creating databases, these database names are directly concatenated with the CREATE DATABASE ... SQL statement. This is because database drivers generally do not support prepared CREATE ... statements.

This also means that you MUST never let users specify tenant IDs themselves, as database names are derived from them by default. If you want tenants to have a user-friendly unique identifier, it’s typically best to add a separate column.

You can set tenancy_db_* attributes for most keys used in database connection configuration. Notably, tenancy_db_name is an exception since it ultimately sets the database key. Some keys may also be ignored or are better suited for template connections than direct attributes on individual tenants — as explained below.

Template connection

Besides values you specify directly on the tenant — on a tenant-by-tenant basis — you can also make tenant connections use some common config. An example use case would be to place all tenant databases on a different server than your primary central database.

To achieve this, take a look at the “template connection” config.

config/tenancy.php

/**
 * Connection used as a "template" for the dynamically created tenant database connection.
 * Note: don't name your template connection tenant. That name is reserved by package.
 */
'template_tenant_connection' => null,

If you create a separate connection in config/database.php (connections section), say tenant_template, you’d set the host for the tenant connections there, then just change this template_tenant_connection to tenant_template.

Then, all tenant connections created for your tenants will be using this host (unless the tenant overrides the default set in the template connection).

By default, the template connection is null, which means that the central connection is used as the template. And what’s the central connection by default? It’s your DB_CONNECTION.

config/tenancy.php

'central_connection' => env('DB_CONNECTION', 'central'),

This may be slightly confusing at first, but ultimately it just means that, in the absence of any customizations:

• your DB_CONNECTION tells Laravel what the default connection is
• Tenancy uses DB_CONNECTION as the central connection
• the central connection is then used as the default template connection
• tenant connections are based on the template connection, merged with any tenant-specific tenancy_db_* attributes

Which is how the package creates tenant databases on the same DB host as your central database — if you don’t tell the package to use anything else, it will use the defaults outlined above.

To customize the template connection, you don’t actually need a named connection in config/database.php. You can directly set template_tenant_connection to an array with your customizations.

Note

Importantly, the above says customizations. If you use a string value, it’s interpreted as the name of a full connection.

On the other hand, if you use an array value, you only need to specify changes compared to the central connection. If you set the value to null, it just uses the central connection.

Or in code form:

src/Database/DatabaseConfig.php

public function getTemplateConnection(): array
{
    if ($template = $this->tenant->getInternal('db_connection')) {
        return config("database.connections.{$template}");
    }

    if ($template = config('tenancy.database.template_tenant_connection')) {
        return is_array($template)
            ? array_merge($this->getCentralConnection(), $template)
            : config("database.connections.{$template}");
    }

    return $this->getCentralConnection();
}

The template connection is never created as a standalone connection, it’s only used to provide the connection definition foundation for the tenant connection. It’s then merged with the tenant’s specific tenancy_db_* attributes (such as tenancy_db_name) to create the tenant connection.

You can also use different (named) template connections on specific tenants. To do that, simply set tenancy_db_connection.

Distributing tenants across multiple database servers

Using tenancy_db_connection is a good way to spread your tenant databases across multiple independent database servers.

This will lower the amount of tenants per database. While many database servers don’t have a fixed limit for the number of databases they can contain, you may still prefer to have a more reasonable number of databases per server (that is if you have thousands of tenants — do not prematurely optimize, most applications will not need this, and as you will see this can be easily added later to an existing app), or perhaps if you need to separate tenant databases by location — such as ensuring your EU tenants have their data stored on EU servers.

The way to achieve this is to simply create multiple connections in the connections section of config/database.php and then set 'tenancy_db_connection' => '...' when creating a tenant. For instance:

• to evenly distribute tenants across N databases, given connections like tenant_server_1, tenant_server_2, …, you can do:

  $connection = 'tenant_server_' . (rand() % $N + 1);
  Tenant::create(['tenancy_db_connection' => $connection]);

• to do a “switch”, as in start sending new tenants to a different database server than existing tenants:

  // can just be hardcoded
  Tenant::create(['tenancy_db_connection' => 'tenant_server_2']);

• to make this region-specific, with connections like tenant_server_na, tenant_server_eu, tenant_server_apac:

  Tenant::create(['tenancy_db_connection' => match ($region) {
      Region::NorthAmerica => 'tenant_server_na',
      Region::AsiaPacific => 'tenant_server_apac',
      Region::Europe, default => 'tenant_server_eu',
  }]);

Of course, if you’re going to be splitting up data across multiple regions, it’s a good idea to have separate web servers as well (and route users to the closest one, with some kind of a region pinning cookie or a similar mechanism). Advice for building distributed applications is outside the scope of this documentation though, this section is primarily meant to illustrate how you can achieve a specific mechanism with Tenancy. Things like this are more within the scope of our e-book.

Host connection

The template connection is used as the foundation for the tenant connection when connecting to an existing tenant.

However, when creating a tenant, we need to create a special connection: the host connection.

The host connection is used to connect to the database server that will host the tenant’s database.

Since the tenant’s database may be on a different server than the default/central connection, and the tenant’s database does not exist yet, we need a database to connect to on the remote server — so that we can establish a connection in the first place — and then we create the tenant’s database on that connection.

The template connection is also used as the foundation for the host connection. Therefore, when establishing the host connection, server details will be taken from the template connection. And as mentioned above, we need some database to connection to, so that database name will be taken from the template connection, which by default is just the central database.

All that is to say: if you create a tenant on a different database server than your central database, e.g. using Tenant::create(['tenancy_db_host' => 'eu.database_servers.acme.com']), Tenancy will by default use your central database name and credentials to connect to that server.

You can deal with this in two main ways:

• You could simply create the central database there (and keep it empty), with the same credentials as on your main server.
• Or, as a better solution, you can just create separate template connections (which all define the right database names and credentials for the “dummy” databases that we initially connect to) as explained above.

We may provide some special tenancy_db_* keys to improve the ergonomics of this in the future. But for now, it’s recommended to simply have pre-defined named connections that you can use as template connections.

The main takeaway from this section is that the database creation/deletion step (anything database managers do) runs on a separate connection, which is mainly based on the template connection. It’s also based on some tenancy_db_* keys but trying to affect the host connection that way can be fragile, as many of those keys are ignored in this step (for details see the DatabaseConfig class in the package source code).

Footnotes

1. This behavior can be customized using the tenancy.database.prefix and tenancy.database.suffix configuration keys. ↩