Tenants

A tenant is a database object that creates a unique and independent namespace for user-defined objects within a database. Additional database objects, including multiple schemas, can be defined within a tenant without concern about a possible name conflict with similar objects in other database tenants.

Any privileges associated with objects defined in a tenant reside and are managed within that tenant. In addition, access to a tenant is explicitly controlled by a new tenant USAGE privilege providing another level of control.

Figure 1. Namespace separation with tenants in a Db2 database
Benefits

With the use of the database tenant concept, it is possible to have multiple independent users (or applications) use the same database without worrying about collision on the object names used by each user or inadvertent exposure to data within those objects. The isolated namespace capability can be leveraged in several ways:

  • Consolidation of smaller, single-user test databases into one shared database with multiple tenants to reduce fixed overhead costs and to simplify operations.
  • The instantiation of multiple independent deployments of the same application within a single shared database environment.
  • Sharing unique hardware configurations, such as those often found in production environments, for advanced testing of application updates prior to moving them into production without risk of contamination or inadvertent access to production data.
  • Ease of migration from other databases with existing multi-tenant implementations without the need to change applications or object names.
Limitations

While the benefits are great, you need to consider the following limitations before implementing tenants in your database:

  • You need to include the schema prefix when running queries, to avoid accidentally querying the incorrect schema.
  • No resource isolation, so tenants share the same processing power and storage. For resource sharing, all tenants share the same catalog table space and, because data isolation is not the default setting, tenants can share the same table spaces for tables and indexes. Also, buffer pools and CPU cycles are completely shared across all tenants.
  • The need for a schema prefix has not changed in this release. The namespace prefix is needed if you want to include a table in the SYSTEM tenant or a schema and table that are named the same in both the SYSTEM tenant and the current tenant.
  • There is a hard limit of 300 user defined tenants.
  • Unlike Db2® local table names, Datalake table names must be unique across all tenants, and not just within a tenant. For more information, see Using Datalake tables in Db2 Warehouse.

The SYSTEM tenant

When a database is created, a default tenant, named SYSTEM, is defined for that database and represents the default database catalogs and environment. The SYSTEM tenant is permanent and does not appear in the tenant definition catalog: the SYSTEM tenant does not appear in the SYSCAT.TENANTS view. The SYSTEM tenant is assigned the unique tenant identifier of 0 (zero). When a user first connects to a database, the user's connection is automatically associated with the default SYSTEM tenant.

Unlike user-defined tenants, there is no USAGE privilege required for the SYSTEM tenant and any connection on the database can associate itself with the SYSTEM tenant.

Database resources and limits

Unless otherwise noted in the documentation, all other database files and output are also considered to be database resources and are shared across all user-defined isolated namespaces. For example, the diagnostic log, transaction logs, and the history file are considered database resources and contain information for all user-defined isolated namespaces in the database. Commands or tools that access these resources return information for all of these namespaces, by default.
Database and SQL limits that apply to shared resources at the database level are still enforced across all user-defined isolated namespaces. They are not applied per namespace.

Shared and private system catalogs

When a tenant is defined, it is given a unique set of system catalog tables to contain information about the database and the objects defined within it. Some of these objects are considered to be global objects for use across the database by all tenants. Others are considered to be local objects that are only known by the individual tenant in which they are defined. The organization of the system catalog tables reflect this division of object definitions by introducing the concept of shared and private system catalog tables.

The set of objects considered to be database resources that are globally known and available to all tenants are stored in a set of shared catalog tables that are used by all tenants. These objects include:

  • Audit objects and policies
  • Buffer pools
  • Groups
  • Roles
  • Storage definitions
  • Table spaces
  • Tenants
  • Users
  • WLM objects

The definitions for these objects are stored in system catalog tables that are shared by all tenants. Objects defined in these catalog tables are visible to users in all tenants (as long as the user has privileges needed to access those catalogs) and all actions and references to these resources act upon the same set of definitions. These catalogs are referred to as shared catalog tables.

The set of objects that are only available within a specific individual tenant include:

  • Aliases
  • Constraints
  • Data types
  • Indexes
  • Modules
  • Packages
  • Routines
  • Schemas
  • Sequences
  • Tables
  • Triggers
  • Variables

The definitions for these objects are kept in system catalog tables that are unique for each individual tenant and are not used by other tenants. These catalog tables are referred to as private catalog tables.

Global database objects

Any object defined in a system catalog that is available to all tenants is referred to as a global object. All the objects defined in a shared catalog table are de facto global objects as they are visible and available to all tenants.

Another set of global objects is represented by the set of database objects defined by Db2 when a database is created. These objects are the various routines, views, modules, etc. defined in the system catalogs when a database is created. Although the definitions for these objects are in the private system catalogs of the default SYSTEM tenant, they are fundamental to the common Db2 experience and functionality.

The set of global database objects is defined as the set of:

  • Any database object, including packages, that are defined in a reserved schema in the SYSTEM tenant.
  • Packages that are defined in the SYSTEM tenant under the NULLID schema by using a reserved package name.

For more information on reserved schemas, see Reserved schema names and reserved words. For more information on reserved packages, see the Reserved package names entry in the topic, Identifiers.

To ensure that all tenant users have the same experience, Db2 treats the objects created by Db2 as implicit global objects, available across all tenants. While not explicitly present in the catalog tables for each tenant, other than the SYSTEM tenant, these objects are automatically included during object resolution within the SQL compiler and other processing. Their inclusion ensures that all tenants have equal access to them.

For example, when the statement “SELECT * FROM SYSCAT.TABLES” is compiled, the catalog view resolves to the private catalog tables of the current tenant. When the same statement is compiled under SYSTEM tenant then it resolves to the database-wide catalog tables stored under the SYSTEM tenant..

The SYSCAT view definitions for those views representing private catalog tables have also been modified to maintain this consistent experience. In addition to the local objects defined in each tenant, the affected views also return these implicit global objects when queried. To help identify them, the name of the tenant where the object is defined appears as the TENANTNAME column in the view output. The implicit global objects return the SYSTEM tenant name, and all local objects return the current tenant name.

Name resolution within a tenant

When an object is referenced with a tenant, the normal name resolution process is followed, and the relevant system catalog tables associated with the tenant are accessed as needed to resolve any references. If the tenant is not the SYSTEM tenant and object schema is one of the schemas reserved by Db2, then Db2 implicitly accesses the SYSTEM tenant catalog tables to look for a matching object definition from the set of objects provided by Db2.

Monitoring within a tenant

The behavior of the administrative routines (and any dependent views) is broken into two different classes:

  • Routines that report information about individual data objects restrict their output to only those objects present in the current tenant.
  • Other interfaces return output for all tenants across the database. .

While event monitors are only be defined in the SYSTEM tenant at this time, these event monitors capture events from all tenants with appropriate tenant information to identify the source of each event.

Tenant integration with database security

A tenant relies on the underlying security infrastructure provided by a Db2 database in the areas of authentication, auditing, and encryption.

Db2 authorization IDs, both primary (users) and secondary (groups, roles) are verified and managed at the database (and instance) level. Roles are defined only in the default SYSTEM catalogs; the contents of the role definition catalog tables are shared across all tenants. Trusted context definitions are also treated in a similar manner.

Audit policies and actions can only be defined at the database level and exist only in the default SYSTEM catalogs. Audit is a database activity and encompasses all activities across tenants. It is not possible to scope an audit policy to a specific tenant nor is it possible to define an audit policy on an object defined in a private tenant catalog.

Encryption, both Transport Layer Security (TLS) and native encryption, is defined and acted upon at a database level. There are no tenant-level configuration options.

LBAC component and policy tables are defined at the SYSTEM level and are shared across all tenants. RCAC definitions are in private catalogs and are unique to each tenant.

Authorization within a user-defined isolated namespace

Authorization within a user-defined isolated namespace is determined by the combination of the authorities and privileges made available to the user at different levels.

Authorization level Description
Database Applies to all objects across all user-defined isolated namespaces.
Tenant Applies only to objects defined with the specific user-defined isolated namespace
Schema Applies to objects defined with the specific schema
Object Applies only to the specific object.

Any authorities or privileges granted at the database or isolated namespace level are recorded in the catalog tables of the SYSTEM tenant. Any authorities or privileges granted at the schema or object level are recorded in the system catalog tables of the user-defined isolated namespace where that schema or object is defined.

When an object in a different isolated namespace is accessed, the authorization for that access is checked by using the authorization information from the isolated namespace where the object is defined and not the one where the access is attempted.

For example, if a query in a user-defined isolated namespace TENANTA refer to both a user-defined table, MYSCHEMA.T1, in that isolated namespace and to the Db2 provided SYSPROC.MON_GET_CONNECTION table function, defined in the SYSTEM tenant, the authorization checks for these objects is resolved in this manner:
MYSCHEMA.T1
The authorization check for accessing this table is resolved by using the relevant database authorities and the relevant authorization catalogs within the TENANTA isolated namespace. The required table privileges to access this function need to be granted within the TENANTA isolated namespace.
SYSPROC.MON_GET_CONNECTION

The authorization check for running the Db2-defined table function is resolved by using the relevant database authorities and the relevant authorization catalogs within the SYSTEM tenant. The required table privileges to access this function need to be granted within the SYSTEM tenant

Workload management

All work being run within a namespace separation participates in the normal database workload management configured for the system without any separation by namespace. If a different workload configuration is desired for a namespace, the TENANT connection attribute for the workload object can be used to separate connections associated with a specific namespace to a distinct workload object and the desired workload configuration can be applied to that workload object or the service class with which the workload is associated.

SQL behavior within a user-defined isolated namespace

The nature of SQL statements determines how they behave within a Db2 user-defined isolated namespace.
Dynamic SQL statements
Since each isolated namespace has its own unique set of catalog tables associated with it, any dynamic SQL prepared within an isolated is also unique and therefore cannot be shared across different user-defined isolated namespaces, only within connections associated with the same isolated namespace. Dynamic SQL statements are qualified by tenant ID when placed in the package cache to ensure that entries are not shared. One consequence of this behavior is that even if different tenant objects are running the same dynamic SQL statements, they each require their own entries in the package cache.
Static SQL statements
Static SQL statements, and their parent packages, are stored as local objects in the system catalogs associated with each isolated namespace. Apart from those packages registered as global objects by Db2, packages cannot be shared between isolated namespaces.
Incremental bind statements
Static SQL statements that are incremental bind statements have their references resolved when they are run. These statements are uniquely resolved within each isolated namespace that references them by using the catalogs associated with that isolated namespace. This means that incremental bind statements are resolved independently in each isolated namespace that references them.
Reserved packages
A specific set of package names have been explicitly reserved for system use. These objects are considered global database objects that are defined only in the SYSTEM tenant. If a user-defined package with a reserved name is bound while in a isolated namespace other than the default SYSTEM tenant, the bind fails (SQLCODE -4004). For a system-provided package that uses a reserved name and that is bound in a isolated namespace other than the default SYSTEM tenant, the system binds the package transparently within the SYSTEM tenant.

Restrictions

Currently, there are some database capabilities that are not yet available within an isolated namespace environment. Where appropriate, these capabilities return a SQL0270N (SQLSTATE 42997) message to indicate that support is not yet present when they are used.

There are some major capabilities that are not yet supported in an isolated namespace:

  • Tenant-specific event monitors. Event monitors can only be created in the SYSTEM tenant and these event monitors collect events from all isolated namespaces.
  • Federation
  • Text Search
  • Usage lists

Some tools and utilities, such as database schema transporting, have also not yet been updated to allow their use within an isolated namespace.