Tenant Database Prefix
Two OctoMesh instances can share one MongoDB server. Each instance has its own system database
(System:SystemDatabaseName, for example OctoSystem and OctoSystemDev), but the tenant databases live side by side
on the same server. A tenant database name can exist only once on the server, so without further settings two instances
cannot both create a tenant meshtest with the default database name: the second create is refused with
Database name 'meshtest' is not available.
The tenant database prefix gives each instance a name space of its own: every new tenant database of the instance
starts with the prefix. The name spaces are only separate when the prefixes do not overlap: an instance without a
prefix can still create a tenant dev_meshtest, whose database is the name the dev_ instance derives for meshtest.
Give every instance on the server a prefix of its own, or reserve the tenant names that overlap.
The setting
| Configuration key | System:TenantDatabasePrefix |
| Environment variable | OCTO_SYSTEM__TENANTDATABASEPREFIX |
Helm (octo-mesh chart) | clusterDependencies.tenantDatabasePrefix |
Helm (octo-mesh-communication-operator chart) | operator.clusterDependencies.tenantDatabasePrefix |
| Default | empty: no prefix, every name as before |
| Format | at most 30 characters, ASCII letters, digits, - and _; stored in lower case |
An invalid value stops the service at start-up with an error that names TenantDatabasePrefix.
Set the same value for every process of an instance: the core services (one chart value for all of them) and the
communication operator, which passes it on to the adapters and workloads it deploys. Use a separator at the end of the
prefix (dev_), so the names stay readable: dev_meshtest.
What changes with a prefix
- Create without a database name: a tenant created without an explicit database name gets the database
<prefix><tenantId>in lower case.octo-cli -c Create -tid meshteston an instance with the prefixdev_creates the databasedev_meshtest. Without a prefix the database is named after the tenant id, as before. - Create or attach with an explicit name: the name must start with the prefix. Any other name is refused with the
same answer as every other unavailable name,
Database name '<name>' is not available.(HTTP 409). The reason is written to the service log only. - Existing tenants keep their names. Tenants that were registered before the prefix was set keep their database, resolve and work as before; there is no rename and no migration. Clearing such a tenant re-creates it under its old name, and a restore over it keeps its name.
- Restore: a restore into a database name without the prefix is refused before anything is written, unless it is
the current database of the same tenant. The refusal gives the same answer,
Database name '<name>' is not available.; the reason is written to the service log only. - Create still refuses a name that already exists on the server, also when it carries the prefix. Attach registers an existing database and a restore can overwrite the tenant's own database; both run the ownership checks (Tenant database ownership). The prefix prevents collisions between instances; it does not let an instance take over a database.
Relation to the CrateDB schema prefix
StreamData:SchemaInstancePrefix (clusterDependencies.streamDataSchemaInstancePrefix) does the same for the CrateDB
schemas of stream data: a tenant's schema becomes <prefix>_<tenantId>. The two settings are independent on purpose.
An instance that already runs with unprefixed CrateDB schemas can set the tenant database prefix without moving its
stream data, and the other way round. A second instance on a shared MongoDB and a shared CrateDB sets both.
Example: two instances on one MongoDB
An installation runs a main instance and a development instance on the same MongoDB and CrateDB:
| Main instance | Development instance | |
|---|---|---|
serviceDefaults.systemDatabaseName | OctoSystem | OctoSystemDev |
clusterDependencies.tenantDatabasePrefix | empty | dev_ |
clusterDependencies.streamDataSchemaInstancePrefix | empty | dev |
Tenant meshtest, created without a database name | database meshtest | database dev_meshtest |
The main instance keeps its names, so nothing moves there. The development instance sets the values in the core chart and in its communication operator chart. Tenants it created before the prefix was set keep their names; new tenants get the prefix, so a test or blueprint with a fixed tenant id runs on both instances.
Local development
Start-Octo -SystemDatabase OctoSystem_s2 -TenantDatabasePrefix s2_ starts a second local instance with its own
system database and prefix. The local octo-devstack daemon gives every stack slot except the default one its own prefix
(<slot prefix>_, for example s2_) together with its own system database.