XM Cloud - Add External Database Locally
Summary
You may have a use case in which you need to add a legacy database to your local XM cloud instance.
It is my understanding that you are not able to add any additional databases to XM Cloud. However, you can add an additional database locally.
We wanted to take content from our Sitecore 7.x legacy database and migrate it, in place, on our new XM Cloud solution. Once migrated, we would serialize that content, using Sitecore Content Serialization, and deploy it to our DEV and PROD XM Cloud instances.
This post will walk you through the details of adding an additional database to your local XM Cloud instance.
Restoring the database
The very first step is to get a backup of the original database that you are trying to add to your local XM Cloud environment. In our case I had recieved a Bak file, but a Bacpac file will work as well.
Place the backup in the data folder in your docker SQL instance:
[Project Root]\docker\data\sql
Next, we need to figure out the IP address to our docker SQL instance. Open up docker for windows and select the copy button next to the cm-1 instance to grab the ID:
Open up a Powershell prompt and paste in the following command with that ID:
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' PLACE-ID-HERE
That will return the IP address for the local XM Cloud SQL instance.
Open up SQL Management Studio and connect to the IP address you retrieved from the command.
Enter in the User Id and Password for the SQL instance. The User Id and Password will be in your docker .env file as SQL_SA_LOGIN and SQL_SA_PASSWORD.
Restore the database backup by referencing the backup you placed in the docker SQL data folder. Refer to the official documentation (opens in a new tab) if needed.
Adding New Configs
In the XM Cloud platform project, create a new config in the App_Config folder called ConnectionStrings.config.
On the docker file system for the CM, copy the ConnectionStrings.config and paste it into the newly created ConnectionStrings.config file. It should look like this:
<?xml version="1.0" encoding="utf-8"?>
<connectionStrings configBuilders="SitecoreConnectionStringsBuilder">
<!--
Sitecore connection strings.
All database connections for Sitecore are configured here.
-->
<add name="core" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_Core" />
<add name="security" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_Security" />
<add name="master" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_Master" />
<add name="web" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_Web" />
<add name="sessions" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_Sessions" />
<add name="azureblob" connectionString="integrated security=true;data source=;database=" />
<add name="solr.search" connectionString="https://localhost:8998/solr" />
<add name="sitecoreidentity.secret" connectionString="Set client secret for Sitecore Identity server here." />
<add name="experienceedge" connectionString="Set the connection string for the experience edge" />
<add name="CMP.ContentHub" connectionString="ClientId={client_id};ClientSecret={client_secret};UserName={username};Password={password};URI={uri};"/>
<add name="CMP.ServiceBusEntityPathIn" connectionString="{Azure Service Bus connection string with incoming topic}"/>
<add name="CMP.ServiceBusSubscription" connectionString="{Subscription name}"/>
<add name="CMP.ServiceBusEntityPathOut" connectionString="{Azure Service Bus connection string with outcoming topic}"/>
<add name="DAM.ContentHub" connectionString="ClientId={client_id};ClientSecret={client_secret};UserName={username};Password={password};URI={uri};"/>
<add name="DAM.SearchPage" connectionString="{Content Hub search page URI}"/>
<add name="DAM.ExternalRedirectKey" connectionString="{External redirect key}"/>
</connectionStrings>Add another entry for the legacy master database. The User Id and Password will be the same values we identified above in the .env file. The IP address was obtained from the Powershell command we originally used for setting up the database.
<add name="master_legacy" connectionString="user id=REPLACE-USER-ID;password=REPLACE-PASSWORD;Data Source=REPLACE-IP-ADDRESS;Database=master_legacy" />In the XM Cloud platform project, create a new config in the App_Config/include folder called legacyMaster.config.
Place a basic Sitecore database configuration patch into that file. For example:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<sitecore>
<databases>
<database patch:after="database[@id='master']" id="master_legacy" singleInstance="true" type="Sitecore.Data.DefaultDatabase, Sitecore.Kernel">
<param desc="name">$(id)</param>
<icon>Images/database_master.png</icon>
<dataProviders hint="list:AddDataProvider">
<dataProvider ref="dataProviders/main" param1="$(id)">
<prefetch hint="raw:AddPrefetch">
<sc.include file="/App_Config/Prefetch/Common.config" />
<sc.include file="/App_Config/Prefetch/Master.config" />
</prefetch>
</dataProvider>
</dataProviders>
<securityEnabled>false</securityEnabled>
<publishVirtualItems>false</publishVirtualItems>
<cacheSizes hint="setting">
<data>100MB</data>
<items>50MB</items>
<paths>2500KB</paths>
<itempaths>50MB</itempaths>
<standardValues>2500KB</standardValues>
</cacheSizes>
<BlobStorage hint="raw:AddBlobStorage">
<providers default="classic">
<provider name="classic" type="Sitecore.Data.Blobs.ClassicSqlBlobProvider, Sitecore.Kernel">
<param desc="databaseName">legacyMaster</param>
</provider>
</providers>
</BlobStorage>
</database>
</databases>
</sitecore>
</configuration>In the XM cloud solution, publish the newly created ConnectionStrings.config and legacyMaster.config. Navigate to the CM, [url]/sitecore/shell, and you should now see another database target added for legacy database:
Conclusion
Although we can not add another database to XM Cloud itself, we can still add it to our local environment. This allows us to leverage legacy content within our XM Cloud solution, for local development or migration. Our use case was very specific to our content migration needs, but there could be other uses as well.