HHH-19559 document schema-based multitenancy

Author: gavinking

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -268,27 +268,56 @@ var entityManager =
 
 However, since we often don't have this level of control over creation of the session, it's more common to supply an implementation of link:{doc-javadoc-url}org/hibernate/context/spi/CurrentTenantIdentifierResolver.html[`CurrentTenantIdentifierResolver`] to Hibernate.
 
-There are three common ways to implement multi-tenancy:
+To make use of multi-tenancy, we'll usually need to set at least one of these configuration properties:
+
+.Multi-tenancy configuration
+[%breakable,cols="36,~"]
+|===
+| Configuration property name           | Purpose
+
+| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_IDENTIFIER_RESOLVER[`hibernate.tenant_identifier_resolver`]  | Specifies the `CurrentTenantIdentifierResolver`
+| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_SCHEMA_MAPPER[`hibernate.multi_tenant.schema_mapper`]  | Specifies the `TenantSchemaMapper` for schema-based multi-tenancy
+| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_CONNECTION_PROVIDER[`hibernate.multi_tenant_connection_provider`]  | Specifies the `MultiTenantConnectionProvider` for database-based multi-tenancy
+|===
+
+// Do not configure those properties if you would like the configured `BeanContainer` provide the implementation.
+
+There are three common approaches to multi-tenancy:
 
 1. each tenant has its own database,
 2. each tenant has its own schema, or
 3. tenants share tables in a single schema, and rows are tagged with the tenant id.
 
-From the point of view of Hibernate, there's little difference between the first two options.
-Hibernate will need to obtain a JDBC connection with permissions on the database and schema owned by the current tenant.
+[discrete]
+==== Database-based multi-tenancy
 
-Therefore, we must implement a link:{doc-javadoc-url}org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.html[`MultiTenantConnectionProvider`] which takes on this responsibility:
+The first option is to give each tenant its own database.
+That is, we'll use a separate source of JDBC connections for each tenant.
+
+The interface link:{doc-javadoc-url}org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.html[`MultiTenantConnectionProvider`] is responsible for obtaining an appropriate `Connection` for a given tenant.
+Typically, we'll provide a custom implementation of this interface:
 
 - from time to time, Hibernate will ask for a connection, passing the id of the current tenant, and then we must create an appropriate connection or obtain one from a pool, and return it to Hibernate, and
 - later, Hibernate will release the connection and ask us to destroy it or return it to the appropriate pool.
 
 [TIP]
 ====
 Check out link:{doc-javadoc-url}org/hibernate/engine/jdbc/connections/spi/DataSourceBasedMultiTenantConnectionProviderImpl.html[`DataSourceBasedMultiTenantConnectionProviderImpl`] for inspiration.
+If your source of JDBC connections is a set of JNDI-bound ``DataSource``s, you might even be able to use this implementation directly.
 ====
 
+[discrete]
+==== Schema-based multi-tenancy
+
+The second option is to keep all the data for different tenants in the same database, giving each tenant a different named database schema with its own set of tables.
+
+In this case we must supply a link:{doc-javadoc-url}org/hibernate/context/spi/TenantSchemaMapper.html[`TenantSchemaMapper`] which is responsible for mapping from tenant ids to schema names.
+
+[discrete]
+==== Discriminator-based multi-tenancy
+
 The third option is quite different.
-In this case we don't need a `MultiTenantConnectionProvider`, but we will need a dedicated column holding the tenant id mapped by each of our entities.
+In this case we store data from all tenants in the same tables, but each table has a dedicated column holding the tenant id mapped by each of our entities.
 
 [source,java]
 ----
@@ -309,20 +338,6 @@ Within a given session, our data is automatically filtered so that only rows tag
 Native SQL queries are _not_ automatically filtered by tenant id; you'll have to do that part yourself.
 ====
 
-To make use of multi-tenancy, we'll usually need to set at least one of these configuration properties:
-
-.Multi-tenancy configuration
-[%breakable,cols="36,~"]
-|===
-| Configuration property name           | Purpose
-
-| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_IDENTIFIER_RESOLVER[`hibernate.tenant_identifier_resolver`]  | Specifies the `CurrentTenantIdentifierResolver`
-| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_CONNECTION_PROVIDER[`hibernate.multi_tenant_connection_provider`]  | Specifies the `MultiTenantConnectionProvider`
-|===
-
-Do not configure those properties if you would like the configured `BeanContainer` provide the implementation.
-A longer discussion of multi-tenancy may be found in the {multitenacy-doc}[User Guide].
-
 [[custom-sql]]
 === Using custom-written SQL