In this guide you are going to build a Multi-Tenant application that utilizes "Database per Tenant" with Grails and GORM 6.1.

Database per tenant allows you to redirect different tenants (users) to different physical databases using a unique tenant identifier.

To complete this guide, you will need the following:

To get started do the following:

or

The Grails guides repositories contain two folders:

To complete the guide, go to the initial folder

and follow the instructions in the next sections.

Since the application requires GORM 6.1.x, the first step is to set your GORM version within gradle.properties:

In order to use Multi-Tenancy you need to setup the Multi-Tenancy mode that GORM uses, given that three distinct modes are supported:

Generally DATABASE and SCHEMA modes can both be considered to be physically separated, whilst DISCRIMINATOR mode requires more care since different tenants' data is stored in the same physical database:

In this case the required Multi-Tenancy mode is DATABASE and it can be configured using the grails.gorm.multiTenancy.mode setting:

Note that, in addition to the mode, the above example configures the tenantResolverClass to use to resolve the tenant.

The tenantResolverClass is a class that implements the TenantResolver interface.

Included within GORM there are several built-in TenantResolver implementations including:

The above implementations are useful to have out-of-the-box, however GORM is flexible and you can implement your own strategy by implementing the TenantResolver interface.

For this example we are going to be using SessionTenantResolver and storing the tenant id within the current user session.

Apart from the default dataSource, we configure two additional data sources audi and ford for each of the tenants:

The names of the data sources correspond to the tenant ids that the configured TenantResolver should return.

When creating domain classes for your application you will typically have domain classes that are Multi-Tenant and others that are not.

For domain classes which won’t be using Multi-Tenancy simply define them as you would normally do and they will be mapped to the default dataSource.

For this example the Manufacturer will be the provider of tenant ids. The name of the Manufacturer will be used as the tenant id allowing access to each configured database:

Next step is to define domain classes that can only be accessed by a given tenant:

The Vehicle and Engine domain classes both implement the MultiTenant trait which results in GORM resolving the database to use from the resulting tenant id returned from the configured TenantResolver.

To setup some test data you can modify the Application class to implement the ApplicationRunner interface to run transactional logic on startup:

In the example about two Manufacturer instances are saved that will correspond to the two tenants supported by this application. The names Audi and Ford are used and correspond to the names of the data sources configured in grails-app/conf/application.yml.

The first step to supporting Multi-Tenancy in your application is implementing some form of tenant selection. This could be to resolve the tenant via a DNS subdomain, or it could be part of your applications registration process if you are using authentication with Spring Security.

To keep things simple for the example we are going to implement a simple mechanism that provides a UI to store the tenantId within the users HTTP session.

First create a new ManufacturerController use create-controller or your preferred IDE:

Next modify the UrlMappings.groovy file to map the root of the application to the index action:

Then define an index action that lists of all the Manufacturers and renders the grails-app/views/index.gsp view.

Within the grails-app/views/index.gsp file, simply iterate through each result and create a link to the select action

The select action, selects the current tenant and stores the tenant within the current user’s HTTP session:

The select action will find a Manufacturer and store the name of the Manufacturer (in lower case so it corresponds to a configured data source) as the current tenant within the HTTP session.

This causes SessionTenantResolver to resolve the correct tenant id from the HTTP session.

Finally, to improve error handling you can map every occurrence of TenantNotFoundException to redirect back to the list of manufacturers:

With these changes in place you will able to select each tenant from the homepage:

Now that it is possible to select a tenant, lets create a logic that is able to use the currently active tenant.

One of the challenges with regards to building an application that uses a unique database connection per tenant is that you have the manage multiple persistence contexts in a scalable manner.

It would not scale to bind a Hibernate session for each and every tenant to each request that came into the application, so you have to be able to write logic that takes into account the fact that the Hibernate session you are using to access the current tenant’s data is not currently bound to the current controller action’s execution.

To make this challenge simpler GORM features a set of Multi-Tenancy transformations including:

These should generally be applied to services in a Grails application and they work really well when combined with the GORM Data Services concept introduced in GORM 6.1.

To implement the logic to save and retrieve Vehicle instances create a new grails-app/services/example/VehicleService.groovy file and annotate it within the CurrentTenant and Service annotations:

Now lets take a look at how to implement querying logic for a Multi-Tenant application.

To implement Multi-Tenant queries in a GORM Data Service simply add abstract methods that correspond to one of the supported conventions in GORM:

The usage of @Join warrants further explanation. Recall that in a Multi-Tenant application a new Hibernate session is created for the connection found for the current tenant id.

Once the method completes however, this session is closed which means that any associations not loaded by the query could lead to a LazyInitializationException due to the closed session.

It is therefore critical that your queries always return the data that is required to render the view. This typically leads to better performing queries anyway and will in fact help you design a better performing application.

The @Join annotation is a simple way to achieve a join query, but in some cases it may be simpler to use a JPA-QL query.

Now it is time to write a controller that can use these newly defined methods. First, create a new grails-app/controllers/example/VehicleController.groovy class with either the create-controller command or your preferred IDE.

The VehicleController should define a property referencing the previously created VehicleService:

Now run grails generate-views to generate some default GSP views that can render the Vehicle instances:

Next add an entry into the UrlMappings.groovy file to map the /vehicles URI:

Now you are ready to add the query logic to read Vehicle instances for each tenant. Update VehicleController with the following read operations:

Both the find and show actions use the VehicleService to locate Vehicle instances. The VehicleService will ensure the correct tenant is resolved and the correct data returned for each tenant.

To add logic to perform write operations you can simply modify the VehicleService and add new abstract methods for save and delete:

The above save and delete methods will be implemented automatically for you.

To implement updates you can add a new method that calls the existing abstract find method:

This demonstrates an important concept of GORM Data Services: It is possible to easily mix methods you define with ones that are automatically implemented for you by GORM.

The corresponding controller actions to call VehicleService and expose these write operations are also trivial:

Testing controller logic that uses Multi-Tenancy requires special considerations.

Luckily GORM 6.1 makes it relatively simple to write unit tests.

To write a unit test for the VehicleController class create a new src/test/groovy/example/VehicleControllerSpec.groovy Spock specification:

As you can see above the test extends HibernateSpec.

To make testing simpler override the tenantResolverClass by overriding the getConfiguration() method of HibernateSpec:

This will allow you to use SystemPropertyTenantResolver for changing the tenant id within the test.

Next step is to provide a setup method that configures the VehicleService for the controller:

To ensure proper cleanup you should also clear the tenant id in a cleanup method:

With that done it is trivial to test the controller logic, for example to test the index action with no data:

You can also write tests to test the case where no tenant id is present by clearing the tenant id:

Testing more complex interactions like saving data is possible too:

Note that within the assertions of the above test we use the vehicleService which makes sure the correct database connection is used when making the assertion.

We map the CRUD pages with the help of Geb Pages:

We test tenant selection with the help of a functional test:

To run the application use the ./gradlew bootRun command which will start the application on port 8080.

Now perform the following steps:

If you then navigate back to the homepage and select "Ford" the current tenant is switched and you can see that if you view the data for the Vehicles for "Ford" the application is now using the ford database, effectively isolating the data between the two tenants.