Skip to main content

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 keySystem:TenantDatabasePrefix
Environment variableOCTO_SYSTEM__TENANTDATABASEPREFIX
Helm (octo-mesh chart)clusterDependencies.tenantDatabasePrefix
Helm (octo-mesh-communication-operator chart)operator.clusterDependencies.tenantDatabasePrefix
Defaultempty: no prefix, every name as before
Formatat 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 meshtest on an instance with the prefix dev_ creates the database dev_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 instanceDevelopment instance
serviceDefaults.systemDatabaseNameOctoSystemOctoSystemDev
clusterDependencies.tenantDatabasePrefixemptydev_
clusterDependencies.streamDataSchemaInstancePrefixemptydev
Tenant meshtest, created without a database namedatabase meshtestdatabase 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.