Skip to content

MS SQL Server

Since v0.27.0

Introduction

The Testcontainers module for MS SQL Server.

Adding this module to your project dependencies

Please run the following command to add the MS SQL Server module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/mssql

Info

To use this module with Go 1.23+, set GODEBUG=x509negativeserial=1. See the related issue in the mssql-docker repository for details.

# append to any existing GODEBUG flags instead of overwriting
export GODEBUG="${GODEBUG:+$GODEBUG,}x509negativeserial=1"

This occurs because: - Go 1.23+ has stricter certificate validation that rejects certificates with negative serial numbers by default - The x509negativeserial=1 flag temporarily re‑enables acceptance of such certificates Note: This stricter check in Go 1.23+ is a security hardening. Prefer using images with fixed certificates (see below). Use the GODEBUG workaround only with affected images and in test environments.

Info

This is fixed in SQL2019 CU32 and SQL2022 CU18 (see SQL Server 2022 CU18 — KB 3867855).

Prefer using container images based on these (or newer) CUs to avoid setting GODEBUG.

Usage example

ctx := context.Background()

password := "SuperStrong@Passw0rd"

mssqlContainer, err := mssql.Run(ctx,
    "mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04",
    mssql.WithAcceptEULA(),
    mssql.WithPassword(password),
)
defer func() {
    if err := testcontainers.TerminateContainer(mssqlContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

EULA Acceptance

Due to licensing restrictions you are required to explicitly accept an End User License Agreement (EULA) for the MS SQL Server container image. This is facilitated through the WithAcceptEULA function.

Please see the microsoft-mssql-server image documentation for a link to the EULA document.

Module Reference

Run function

Info

The RunContainer(ctx, opts...) function is deprecated and will be removed in the next major release of Testcontainers for Go.

The MS SQL Server module exposes one entrypoint function to create the MS SQL Server container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MSSQLServerContainer, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "mcr.microsoft.com/mssql/server:2022-RTM-GDR1-ubuntu-20.04").

Container Options

When starting the MS SQL Server container, you can pass options in a variadic way to configure it.

WithInitSQL

If you need to execute SQL files when the container starts, you can use mssql.WithInitSQL(files ...io.Reader) with one or more *.sql files. The files will be executed in order after the container is ready.

CREATE SCHEMA pizza_palace;
GO

CREATE TABLE pizza_palace.pizzas (
    ID INT PRIMARY KEY IDENTITY,
    ToppingName NVARCHAR(100),
    Deliciousness NVARCHAR(100) UNIQUE
);
GO

INSERT INTO pizza_palace.pizzas (ToppingName, Deliciousness) VALUES
    ('Pineapple', 'Controversial but tasty'),
    ('Pepperoni', 'Classic never fails')
GO

This will:

  1. Copy each file into the container.
  2. Execute them using sqlcmd after the container is ready.

WithAcceptEula

Due to licensing restrictions you are required to explicitly accept an EULA for this container image. To do so, you must use the function mssql.WithAcceptEula(). Failure to include this will result in the container failing to start.

WithPassword

If you need to set a different MS SQL Server password, you can use mssql.WithPassword with a valid password for MS SQL Server. E.g. mssql.WithPassword("SuperStrong@Passw0rd").

Info

If you set a custom password string, it must adhere to the MS SQL Server Password Policy.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Container Methods

The MS SQL Server container exposes the following methods:

ConnectionString

This method returns the connection string to connect to the Microsoft SQL Server container, using the default 1433 port. It's possible to pass extra parameters to the connection string, e.g. encrypt=false or TrustServerCertificate=true, in a variadic way.

connectionString, err := container.ConnectionString(ctx, "encrypt=false", "TrustServerCertificate=true")