How to link a SQL Server database to a Mercurial repository

Applies to
ApexSQL Source Control

This article describes how to link a SQL Server database to a Mercurial repository. Since a Mercurial repository can be accessed in various ways (using different protocols), we’ll go through these cases one by one.

Quick tip icon

Quick tip:

When working with Mercurial it is a requirement to have a Mercurial command line client installed on the same machine where ApexSQL Source Control is installed. Any of the source install, Inno Setup Installer or MSI installer contain the command line client, as well as TortoiseHg executable. No additional configuration is required after the installation.


The following protocols will be used: file, HTTP and HTTPS and SSH.

To link a database to a Mercurial repository, follow the common steps through the Source control wizard. These steps are covered in the How to link a database to source control.

Note: The information describing the steps common to all source control systems is not included in this article.

The goal of this article is to cover various ways of linking a database to a Mercurial repository with a focus on specific information (parameters) that should be used in the Source Control wizard depending on the used Mercurial repository.

The first step in order to link a database to any Mercurial repository is to make sure that the Mercurial item is selected in the Connection type step from the Source control system drop down list:

When Mercurial is selected in the first step, the System login step is as follows:

Mercurial on a local file system (file protocol)

To demonstrate how to link a database to a Mercurial repository hosted by the local file system, TortoiseHg will be used. TortoiseHg is a free Mercurial client that integrates into Windows as a shell component. This means that a folder on a local file system can be created and in a few clicks initialized as a Mercurial repository.

Quick tip icon

Quick tip:

In addition to TortoiseHg, any other Mercurial client can be used to initialize or clone a Mercurial repository.

In order to use a local folder as a Mercurial repository, it has to be either initialized or a remote Mercurial repository needs to be cloned to a local folder. To initialize a Mercurial repository, we’ll create a folder on a local file system, called MercurialRepo and while the folder is opened, right click to bring up the context menu. If TortoiseHg is installed, there should be a menu item called Create repository here:

This option opens the New repository dialog:

Clicking the Create button will initialize the selected folder as a Mercurial repository.

As shown in the New repository dialog, there is a Mercurial command that can be executed to initialize a folder as a repository, instead of using the context menu option. In this specific case, a command is as follows:

hg init –config “C:\ MercurialRepo”

Either by using the context menu in Windows Explorer or a command executed through the CLI, the result will be a folder structure which represents a mercurial repository:

Quick tip icon

Quick tip:

The Mercurial command line component comes with the TortoiseHg installation. However, it can be installed as a separate component.

Once the repository is initialized, we can link a database using the full path as a parameter for the Repository field in the System login step:

Quick tip icon

Quick tip:

Besides initializing a repository, a remote repository can be cloned to a local file system and used in the same way as the initialized one.

The following command will clone a remote Mercurial repository in a local folder;

hg clone

Username and Password

When working with a local file system, username and password are not required in most of the cases, since the current user will have the necessary permissions and the folder selected to be a Mercurial repository will not be password protected.

In order to avoid specifying username and password, a necessary step, before pasting the path in the Repository field under the System login tab is to specify the file:\\\ part first:

This will grey out the Username and Password fields and will add a caption in the Username field that credentials are not mandatory.

Quick tip icon

Quick tip:

If the local Mercurial repository is on a location that is password protected, specifying a password is still available by simply providing a username and password before providing the file:\\\ part in the Repository field.


The Project field allows the user to create a separate folder/project for any database (which is recommended), directly from the Source control wizard and without the need to switch from SQL Server Management Studio to any other application. To browse for the existing projects, use the Browse button to open the Choose project dialog:

Quick tip icon

Quick tip:

When creating a Mercurial project inside the repository it is mandatory to provide a description.


To show how to utilize HTTP and HTTP protocols we’ll use as an online Mercurial repository service.

When the new Mercurial repository is created, the following URL fill be available:


For instance, if the username on Bitbucket is SQLDev and a repository that is created is RemoteMercurial, the following is the URL that will be generated:

To link a database to the remote repository, its URL must be provided as a parameter for the Repository field under the System login step:

Quick tip icon

Quick tip:

Some online Mercurial repository hosting services require an account username and a password for authentication, while others require an email in combination with a password for the user account.

Using the SSH protocol

Detailed steps on how to generate SSH key pair as well as how to add a public key to a Bitbucket repository is described in How to link SQL Server database to a Git repository article, under the Git with SSH section. By following the given steps there should be a public key added to the Mercurial repository hosted on Bitbucket.

Once the key is added, a generated SSH URL can be used along with the specified passphrase instead of a password that is used for HTTP(S) URL:

Q: Is it possible to link a database to a repository that is on a machine in the same domain as the machine where SQL Server Management Studio and ApexSQL Source Control are installed?

A: Yes, if the machine where the Mercurial repository is hosted is in the same domain as a machine where ApexSQL Source Control is installed, a database can be linked either using Windows credentials or without them.

Q: What happens if a description for the created project inside the Mercurial repository is not specified?

A: A validation message appears informing the user that a description is mandatory when creating a new project.

Q: How can I update the password for linking a database, if it is changed after a database is linked?

A: Unlinking a database and linking it to the same repository allows the user to specify a password in the final step of the wizard. Instead of using the saved password, specify a new one and proceed with the linking process.