Adding a custom database to Sitecore container stack

How databases are mounted and connectionstrings passed through on Sitecore containers.

Sitecore 10 introduces official support to containerized development with Docker. Some of the applications we are developing require custom databases. Let’s find out how we can add them into our container stack.

1. Add your database to SQL container

In our first step, we will mount our custom database into our sitecore-*-mssql container. In order to do so, we just need to make sure that our database MDF and LDF file is copied into the mssql image inside the c:\install directory. When doing so, the databases will be automaticaly picked up and attached when creating the container.

The way that this works is because if you start the mssql container, the startdatabases.ps1 script located in the image is executed. In this script all files ending with *.mdf inside the install directory are scanned and mounted into the sqlserver. The script will search for a corresponding *.ldf file. You want to make sure that the names of the mdf and ldf files correspond so that the script can match them.

 Get-ChildItem -Path $DataDirectory -Filter "*.mdf" | ForEach-Object {
     $databaseName = $_.BaseName.Replace("_Primary", "")
     $mdfPath = $_.FullName
     $ldfPath = Get-ChildItem -Path $DataDirectory -Filter "$databaseName*.ldf" | Select-Object -First 1
     $ldfPath = $ldfPath.FullName
     $sqlcmd = "IF EXISTS (SELECT 1 FROM SYS.DATABASES WHERE NAME = '$databaseName') BEGIN EXEC sp_detach_db [$databaseName] END;CREATE DATABASE [$databaseName] ON (FILENAME = N'$mdfPath'), (FILENAME = N'$ldfPath') FOR ATTACH;"
     Write-Host "INFO: Attaching '$databaseName'..."
     & sqlcmd -Q $sqlcmd

fragment from startdatabases.ps1

To add our custom database into the image we will need to contruct a custom image from our default base mssql image with DockerFile build. To do so, add a mssql section in the docker-compose.override.yml file.

Next, let’s setup our docker build by copying our mdf and ldf file info ./docker/build/mssql/customdatabases directory.

Next, we need to write our DockerFile in ./docker/build/mssql. In here we just need to add the instruction to copy our CustomDatabases into the install directory.

2. Set the connection string

Now that our database is mounted and available, we want enable our application to connect to it.

When youlook at the connectionstrings on the cm/cd role. (App_Config/connectionstring.config), you will notice that this file doesn’t contain the actual connectionstrings. All the connectionstrings are defined here, but their values are dummies. The connectionstrings.config file refers to the configBuilder “SitecoreConnectionStringsBuilder”. Configbuilders are a fairly new concept in .NET and when we look in the web.config, you will find that the “SitecoreConnectionStringsBuilder” uses the Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder class. In essence, this class will read the connectionstring from the environment settings. The config section also defines that the connectionstrings are prefixed with “Sitecore_ConnectionStrings_”

<add name="SitecoreConnectionStringsBuilder" mode="Strict" prefix="SITECORE_CONNECTIONSTRINGS_" stripPrefix="true" type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment, Version=, Culture=neutral"/>

If you have a look at the docker-compose.yml file, you will notice that all connection strings are passed through here to the environment settings.

To add our custom database connection string we need 2 steps:

  1. Add a dummy entrance with dummy value in the connectionstrings.config file.
  2. Pass the correct connectionstring value via dock-compose.override.yml

To modify the connectionstring.config file, you can just take a copy of the original file, modify it and past it into your solution. You can opt to merge it into the image with the Dockerfile build, or just add it into your visual studio solution to get it published with the rest of the code.

Overriding the connectionstring is even easier. Just add an extra environment variable in docker-compose.override.yml

Leave a Reply