install-sql-server

This action installs and runs SQL Server for a GitHub Actions workflow. Also adds support for sqlcmd.

1. Runs SQL Server in a Linux Docker container on every platform.

• On Linux, the container runs directly via Docker using the mcr.microsoft.com/mssql/server:2022-latest image.
• On Windows, the Linux container runs inside WSL2 (the action installs and starts Docker inside the WSL distribution).
• Sets collation to case sensitive SQL_Latin1_General_CP1_CS_AS note SQL Azure is insensitive CI_AS

1. Creates environment variables for a connection string and for sqlcmd.
2. Waits for the SQL instance to be accessible.
3. Creates a default database catalog.

Note

Because this is a composite action, it has no cleanup/post step (GitHub does not support post steps for composite actions). On hosted runners this is fine — the runner VM is destroyed at the end of the job, taking the container (and, on Windows, the WSL distribution) with it.

Usage

Install SQL Server 2022 with a default database of nservicebus and put the connection string in the environment variable SQL_SERVER_CONNECTION_STRING:

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      catalog: nservicebus

It is also possible to specify the SQl server major version to be installed

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      sqlserver-version: 2019
      catalog: nservicebus

To add additional parameters to the end of the connection string, such as Max Pool Size. The connection string generated by the action already ends with a semicolon, and the extra-params are appended at the end.

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      catalog: nservicebus
      extra-params: "Max Pool Size=100;"

To enable SQL Server Full-Text Search:

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      catalog: nservicebus
      enable-full-text-search: "true"

To enable distributed transactions (MSDTC) in the container:

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      catalog: nservicebus
      enable-distributed-transactions: "true"

Parameters

Parameter	Required	Default	Description
connection-string-env-var	Yes	-	Environment variable name that will be filled with the SQL connection string, which can then be used in successive steps.
catalog	No	nservicebus	The default catalog, which will be created by the action.
collation	No	SQL_Latin1_General_CP1_CS_AS	The collation to use for the SQL Server database. Override to any available SQL collation.
sqlserver-version	No	2022	The SQL server major version to use.
extra-params	No	-	Extra parameters to be appended to the end of the connection string.
enable-full-text-search	No	"false"	When set to "true", the action installs/enables and verifies SQL Server Full-Text Search before completion.
enable-distributed-transactions	No	"false"	When set to "true", configures the container for the Microsoft Distributed Transaction Coordinator (MSDTC) so SQL Server can participate in distributed transactions.

When enable-full-text-search is enabled, setup time may increase because extra SQL components/packages are installed. On both Linux and Windows the SQL Server container is the same Linux image, so Full-Text Search is added by installing the matching mssql-server-fts apt package for the requested SQL Server major version. Current Full-Text Search setup support includes SQL Server major versions 2019, 2022, and 2025.

When enable-distributed-transactions is enabled, the action sets the MSSQL_RPC_PORT and MSSQL_DTC_TCP_PORT environment variables and publishes the corresponding ports (135 and 51000) on the container, following the SQL Server Linux container distributed transactions guidance. SQL Server 2019 and later containers run as a non-root user and cannot bind to the privileged RPC port 135, so the RPC endpoint mapper listens on 13500 and the action maps host port 135 to it. On Windows the ports are published inside the WSL2 VM and are reachable from the host via the WSL IP (the same address used in the connection string).

Because the previous Windows path ran a native SQL Server Express instance on the same host, distributed transactions were coordinated by the local DTC and worked without any configuration. Running SQL Server in a WSL2 container turns those into network transactions, so on Windows the action additionally configures the host's Local DTC when this input is set: it enables Network DTC Access (inbound and outbound), sets the authentication level to No Authentication Required (the Linux container's MSDTC does not authenticate RPC), allows the Distributed Transaction Coordinator through Windows Firewall, sets the container's hostname to sqlserver, and adds a Windows hosts file entry mapping that name to the WSL2 IP. The hostname mapping is necessary because the container's DTC advertises its hostname in its transaction "whereabouts" — without a resolvable name the host DTC cannot push the transaction (see mssql-docker#492). This restores the previous "it just works" behavior for consumers' distributed-transaction tests.

Note

.NET 7+ opt-in: Since .NET 7, TransactionManager.ImplicitDistributedTransactions defaults to false, meaning TransactionScope escalation to MSDTC throws NotSupportedException unless the application explicitly sets TransactionManager.ImplicitDistributedTransactions = true at startup. This is a per-process setting the action cannot set for consumers. If your tests use distributed transactions, add this one line to your test setup:

TransactionManager.ImplicitDistributedTransactions = true;

Connection string

The generated connection string uses SQL authentication (User Id=sa;Password=...;Encrypt=false;):

• On Linux the data source is localhost (Server=localhost;...).
• On Windows the data source is the WSL2 VM IP address (Server=<wsl-ip>;...) so that the host can reach the container. The WSL_DISTRIBUTION_OVERRIDE and WSL_MEMORY_OVERRIDE environment variables can be set to override the distribution name (default Debian) and the .wslconfig memory limit (default 4GB) respectively.

Using sqlcmd

The action also makes it possible to run sqlcmd. How it does this is different based on platform:

• Windows: The runner's native sqlcmd (installed via the SQL Server Command Line Utilities) is wrapped in a small sqlcmd.cmd shim that injects -C so the container's self-signed certificate is trusted. The action sets the SQLCMDSERVER, SQLCMDUSER, and SQLCMDPASSWORD environment variables (pointing at the WSL container), so sqlcmd can be used without any additional login parameters. For larger scripts, prefer sqlcmd -i <file> over passing multi-line arguments inline.
• Linux: A bash script named sqlcmd is created and added to the PATH. All commands to it are forwarded to the Docker container via docker exec. The Docker container is initialized with environment variables so that login parameters are not necessary.

For example:

steps:
  - name: Install SQL Server
    uses: Particular/install-sql-server-action@v1.4.0 # Check if this is the latest version at https://github.com/Particular/install-sql-server-action/tags
    with:
      connection-string-env-var: SQL_SERVER_CONNECTION_STRING
      catalog: nservicebus
  - name: Create schemas
    shell: pwsh
    run: |
        echo "Create additional schemas"
        sqlcmd -Q "CREATE SCHEMA receiver AUTHORIZATION db_owner" -d "nservicebus"
        sqlcmd -Q "CREATE SCHEMA sender AUTHORIZATION db_owner" -d "nservicebus"
        sqlcmd -Q "CREATE SCHEMA db@ AUTHORIZATION db_owner" -d "nservicebus"