How to link a SQL Server database to a Mercurial repository

Applies to

ApexSQL Source Control

Summary

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 contains the command-line client, as well as TortoiseHg executable. No additional configuration is required after the installation

Description

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

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

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 setup window 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 tab from the Source control system drop-down list:

The Connection tab in the Source control setup window when linking a database to Mercurial repository

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

The System login tab in the Source control setup window when linking a database to Mercurial repository

Linking a database to a Mercurial repository using the 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:

Creating local Mercurial repository using TortoiseHG - right-click context menu

This option opens the New repository dialog:

Creating local Mercurial repository using TortoiseHG - New repository window

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=hooks.post-init.thgskel=python:tortoisehg.util.hgcommands.postinitskel “C:\Users\Mara\Desktop\Mercurial”

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:

The folder structure of the Mercurial local 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 tab:

The System login tab when linking a database to a local Mercurial repository - the repository path

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 https://SQLDev@bitbucket.org/SQLDev/remotemercurial

Username and Password

When working with a local file system, a 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. By default the username and password are not mandatory when working with Mercurial over the File protocol:

The System login tab when linking a database to a local Mercurial repository - the username and password

Project

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

The System login tab when linking a database to a local Mercurial repository - Creating a new project

Quick tip icon

Quick tip:

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

Linking a database to a Mercurial repository using HTTP and HTTPS protocols

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

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

https://<username>@bitbucket.org/<username>/<repository_name>

For instance, if the username on Bitbucket.org is krusho and a repository that is created is mercurial_1, the following is the URL that will be generated:

https://krusho@bitbucket.org/krusho/mercurial_1

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

The System login tab when linking a database to a cloud Mercurial repository using HTTPS protocol - the repository path

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

Linking a database to a Mercurial repository using SSH protocol

Detailed steps on how to generate SSH key pair as well as how to add a public key to a Bitbucket.org repository are described in the How to link SQL Server database to a Git repository article.

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:

The System login tab when linking a database to a cloud Mercurial repository using SSH protocol

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.

Information message when missing the new project comment

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 Source control setup window. Instead of using the saved password, specify a new one and proceed with the linking process.