Tenants
Every named tenant gets a PostgreSQL database of its own. Andromeda creates it the first time a request needs it, and drops it again only if the tenant never ends up holding anything. The default tenant lives in the database that database.connection names.
What a client sees of tenants is under Tenants. This page covers what happens on the server.
Creating a tenant's database
Each named tenant's database is named from the tenant name and tenancy.databases.name_prefix, which defaults to andromeda_tenant.
To decide a creating request, Andromeda often needs the tenant's database first. It checks, for example, whether an identifier is already taken. So when such a request names a tenant that doesn't exist yet, Andromeda registers the tenant as provisional. It then creates and migrates the database before the operation runs. The tenant counts as existing only once its database holds information.
A request that may create a new tenant creates and migrates its database first, even if the request is then refused.
Setting up the database can take a while on a busy server. A request waits for it for up to tenancy.build.admission_timeout, then gets 503 with Retry-After while the setup goes on. A retry waits for that same setup rather than starting another, and is served once it is done. If the setup is cut short, for example by a lost connection or a broker restart, the request gets 503 with Retry-After too, and the next request for that tenant picks the setup up where it stopped.
A tenant that is only ever written to, and never read, is fully registered within one tenancy.residency.sweep_interval of holding information. From then on, maintenance looks after it too.
Cleaning up empty tenants
Every tenancy.residency.sweep_interval, Andromeda looks for provisional tenants whose database still holds nothing. Once one is older than tenancy.provisional_tenant_lifetime, it drops the empty database and removes the registration.
That is the only kind of tenant database Andromeda ever drops, and it is careful about it.
- It never drops a database that holds information.
- It never drops a database while any session is connected to it.
What refused requests cost
A creating request that names a new tenant still creates, migrates and later drops a database, even when the request itself is refused. You might expect a refused request to leave nothing behind. It doesn't.
A client that keeps sending tenant names it never manages to write to costs you one database per name, for up to tenancy.provisional_tenant_lifetime each.
Removing a tenant
No API call deletes a tenant or drops its database, because dropping a database can't be undone. That stays your decision.
To remove a tenant, suspend it first through tenant management, so its connections close. Then drop its database yourself.
A tenant database left behind without a registration, for example by a removal that stopped half way, is reported on every maintenance pass as orphan-tenant-database. Andromeda never drops it.
Configuration
| Key | Default | What it does |
|---|---|---|
tenancy.databases.name_prefix | andromeda_tenant | The prefix every tenant database name starts with |
tenancy.provisional_tenant_lifetime | "10m" | How long an empty provisional tenant is kept before its database is dropped |
tenancy.residency.sweep_interval | "30s" | How often Andromeda checks for empty provisional tenants and idle tenant runtimes |
Pool sizes and how many tenants stay loaded at once are under Database connections.
If it goes wrong
Where Andromeda interprets the specification
NGSI-LD v1.9.1 clause 5.5.10 lets a broker create tenants implicitly, and it lists the operations that do. The 503 for an interrupted setup follows clauses 5.5.6 and 5.5.10.