Skip to content

sql-server-linux-docker-container-deployment.md

Latest commit

 

History

History
450 lines (334 loc) · 19.9 KB

sql-server-linux-docker-container-deployment.md

File metadata and controls

450 lines (334 loc) · 19.9 KB
title Deploy and connect to SQL Server Docker containers
description Explore how SQL Server can be deployed on Docker containers and learn about various tools to connect to SQL Server from inside and outside the container
author amvin87
ms.author amitkh
ms.reviewer vanto, randolphwest
ms.custom
contperf-fy21q1
intro-deployment
ms.date 02/22/2022
ms.topic conceptual
ms.service sql
ms.subservice linux
moniker >= sql-server-linux-2017 || >= sql-server-2017
zone_pivot_groups cs1-command-shell

Deploy and connect to SQL Server Docker containers

[!INCLUDE SQL Server - Linux]

This article explains how to deploy and connect to SQL Server Docker containers.

For other deployment scenarios, see:

Note

This article specifically focuses on using the mssql-server-linux image. SQL Server deployments in Windows containers are not covered by support. For development and testing, you can create your own custom container images to work with SQL Server in Windows containers. Sample files are available on GitHub. Sample files are for reference only.

Important

Before choosing to run a SQL Server container for production use cases, please review our support policy for SQL Server Containers to ensure that you are running on a supported configuration.

This 6-minute video provides an introduction into running SQL Server on containers:

[!VIDEO https://channel9.msdn.com/Shows/Data-Exposed/SQL-Server-2019-in-Containers/player?WT.mc_id=dataexposed-c9-niner]

Pull and run the container image

To pull and run the Docker container images for [!INCLUDEsssql17-md] and [!INCLUDEsssql19-md], follow the prerequisites and steps in the following quickstart:

This configuration article provides additional usage scenarios in the following sections.

Connect and query

You can connect and query SQL Server in a container from either outside the container or from within the container. The following sections explain both scenarios.

Tools outside the container

You can connect to the SQL Server instance on your Docker machine from any external Linux, Windows, or macOS tool that supports SQL connections. Some common tools include:

The following example uses sqlcmd to connect to SQL Server running in a Docker container. The IP address in the connection string is the IP address of the host machine that is running the container.

::: zone pivot="cs1-bash"

sqlcmd -S 10.3.2.4 -U SA -P '<YourPassword>'

::: zone-end

::: zone pivot="cs1-powershell"

sqlcmd -S 10.3.2.4 -U SA -P "<YourPassword>"

::: zone-end

::: zone pivot="cs1-cmd"

sqlcmd -S 10.3.2.4 -U SA -P "<YourPassword>"

::: zone-end

If you mapped a host port that wasn't the default 1433, add that port to the connection string. For example, if you specified -p 1400:1433 in your docker run command, then connect by explicitly specifying port 1400.

::: zone pivot="cs1-bash"

sqlcmd -S 10.3.2.4,1400 -U SA -P '<YourPassword>'

::: zone-end

::: zone pivot="cs1-powershell"

sqlcmd -S 10.3.2.4,1400 -U SA -P "<YourPassword>"

::: zone-end

::: zone pivot="cs1-cmd"

sqlcmd -S 10.3.2.4,1400 -U SA -P "<YourPassword>"

::: zone-end

Tools inside the container

Starting with [!INCLUDEsssql17-md], the SQL Server command-line tools are included in the container image. If you attach to the image with an interactive command-prompt, you can run the tools locally.

  1. Use the docker exec -it command to start an interactive bash shell inside your running container. In the following example e69e056c702d is the container ID.

    docker exec -it e69e056c702d "bash"

    [!TIP] You don't always have to specify the entire container ID. You only have to specify enough characters to uniquely identify it. So in this example, it might be enough to use e6 or e69 rather than the full ID. To find out the container ID, run the command docker ps -a.

  2. Once inside the container, connect locally with sqlcmd by using its full path.

    /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P '<YourPassword>'

  3. When finished with sqlcmd, type exit.

  4. When finished with the interactive command-prompt, type exit. Your container continues to run after you exit the interactive bash shell.

Check the container version

If you want to know the version of SQL Server in a running Docker container, run the following command to display it. Replace <Container ID or name> with the target container ID or name. Replace <YourStrong!Passw0rd> with the SQL Server password for the system administrator (SA) account.

::: zone pivot="cs1-bash"

sudo docker exec -it <Container ID or name> /opt/mssql-tools/bin/sqlcmd \
-S localhost -U SA -P '<YourStrong!Passw0rd>' \
-Q 'SELECT @@VERSION'

::: zone-end

::: zone pivot="cs1-powershell"

docker exec -it <Container ID or name> /opt/mssql-tools/bin/sqlcmd `
-S localhost -U SA -P "<YourStrong!Passw0rd>" `
-Q "SELECT @@VERSION"

::: zone-end

::: zone pivot="cs1-cmd"

docker exec -it <Container ID or name> /opt/mssql-tools/bin/sqlcmd ^
-S localhost -U SA -P "<YourStrong!Passw0rd>" ^
-Q "SELECT @@VERSION"

::: zone-end

You can also identify the SQL Server version and build number for a target Docker container image. The following command displays the SQL Server version and build information for the mcr.microsoft.com/mssql/server:2019-latest image. It does this by running a new container with an environment variable PAL_PROGRAM_INFO=1. The resulting container instantly exits, and the docker rm command removes it.

::: zone pivot="cs1-bash"

sudo docker run -e PAL_PROGRAM_INFO=1 --name sqlver \
-ti mcr.microsoft.com/mssql/server:2019-latest && \
sudo docker rm sqlver

::: zone-end

::: zone pivot="cs1-powershell"

docker run -e PAL_PROGRAM_INFO=1 --name sqlver `
-ti mcr.microsoft.com/mssql/server:2019-latest; `
docker rm sqlver

::: zone-end

::: zone pivot="cs1-cmd"

docker run -e PAL_PROGRAM_INFO=1 --name sqlver ^
-ti mcr.microsoft.com/mssql/server:2019-latest && ^
docker rm sqlver

::: zone-end

The previous commands display version information similar to the following output:

sqlservr
  Version 15.0.4198.2
  Build ID 52e9e8d493d41fd93627371c4c7d3e2a6b52a65f47f07c8c737931a208c45824
  Build Type release
  Git Version d6f11919
  Built at Sat Jan 22 05:09:51 GMT 2022

PAL
  Build ID 2d0b057b139c49b6933e896f56af464a2893fd9aa3da2e2a709d5fc220cb0225
  Build Type release
  Git Version 52a534725
  Built at Sat Jan 22 05:07:25 GMT 2022

Packages
  system.security                         6.2.9200.11,52a534725+hls-win4-20220122044858,
  system.certificates                     6.2.9200.11,52a534725+hls-win4-20220122044858,
  secforwarderxplat                       15.0.4198.2
  sqlservr                                15.0.4198.2
  system.common                           10.0.17134.2145.202104262
  system.netfx                            4.7.0.0.202104262
  system                                  6.2.9200.11,52a534725+hls-win4-20220122044858,
  sqlagent                                15.0.4198.2

Run a specific SQL Server container image

Note

There are scenarios where you might not want to use the latest SQL Server container image. To run a specific SQL Server container image, use the following steps:

  1. Identify the Docker tag for the release you want to use. To view the available tags, see the mssql-server-linux Docker hub page.

  2. Pull the SQL Server container image with the tag. For example, to pull the 2019-CU15-ubuntu-20.04 image, replace <image_tag> in the following command with 2019-CU15-ubuntu-20.04.

    docker pull mcr.microsoft.com/mssql/server:<image_tag>

  3. To run a new container with that image, specify the tag name in the docker run command. In the following command, replace <image_tag> with the version you want to run.

    [!IMPORTANT]
    The SA_PASSWORD environment variable is deprecated. Please use MSSQL_SA_PASSWORD instead.

    ::: zone pivot="cs1-bash"

    docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' -p 1401:1433 -d mcr.microsoft.com/mssql/server:<image_tag>

    ::: zone-end

    ::: zone pivot="cs1-powershell"

    docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:<image_tag>

    ::: zone-end

    ::: zone pivot="cs1-cmd"

    docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:<image_tag>

    ::: zone-end

These steps can also be used to downgrade an existing container. For example, you might want to roll back or downgrade a running container for troubleshooting or testing. To downgrade a running container, you must be using a persistence technique for the data folder. Follow the same steps outlined in the upgrade section, but specify the tag name of the older version when you run the new container.

::: moniker range=">= sql-server-linux-ver15 || >= sql-server-ver15 "

Run RHEL-based container images

The documentation for SQL Server Linux container images points to Ubuntu-based containers. Beginning with [!INCLUDEsssql19-md], you can use containers based on Red Hat Enterprise Linux (RHEL). An example of the image for RHEL will look like mcr.microsoft.com/mssql/rhel/server:2019-CU15-rhel-8.

For example, the following command pulls the Cumulative Update 15 for [!INCLUDEsssql19-md] container that uses RHEL 8:

::: zone pivot="cs1-bash"

sudo docker pull mcr.microsoft.com/mssql/rhel/server:2019-CU15-rhel-8.4

::: zone-end

::: zone pivot="cs1-powershell"

docker pull mcr.microsoft.com/mssql/rhel/server:2019-CU15-rhel-8.4

::: zone-end

::: zone pivot="cs1-cmd"

docker pull mcr.microsoft.com/mssql/rhel/server:2019-CU15-rhel-8.4

::: zone-end

::: moniker-end

Run production container images

The quickstart in the previous section runs the free Developer edition of SQL Server from Docker Hub. Most of the information still applies if you want to run production container images, such as Enterprise, Standard, or Web editions. However, there are a few differences that are outlined here.

  • You can only use SQL Server in a production environment if you have a valid license. You can obtain a free SQL Server Express production license here. SQL Server Standard and Enterprise Edition licenses are available through Microsoft Volume Licensing.

  • The Developer container image can be configured to run the production editions as well. Use the following steps to run production editions:

Review the requirements and run procedures in the quickstart. You must specify your production edition with the MSSQL_PID environment variable. The following example shows how to run the latest [!INCLUDEsssql19-md] container image for the Enterprise Edition:

::: zone pivot="cs1-bash"

docker run --name sqlenterprise \
-e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' \
-e 'MSSQL_PID=Enterprise' -p 1433:1433 \
-d mcr.microsoft.com/mssql/server:2019-latest

::: zone-end

::: zone pivot="cs1-powershell"

docker run --name sqlenterprise `
-e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" `
-e "MSSQL_PID=Enterprise" -p 1433:1433 `
-d "mcr.microsoft.com/mssql/server:2019-latest"

::: zone-end

::: zone pivot="cs1-cmd"

docker run --name sqlenterprise `
-e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" ^
-e "MSSQL_PID=Enterprise" -p 1433:1433 ^
-d "mcr.microsoft.com/mssql/server:2019-latest"

::: zone-end

Important

By passing the value Y to the environment variable ACCEPT_EULA and an edition value to MSSQL_PID, you are expressing that you have a valid and existing license for the edition and version of SQL Server that you intend to use. You also agree that your use of SQL Server software running in a Docker container image will be governed by the terms of your SQL Server license.

Note

For a full list of possible values for MSSQL_PID, see Configure SQL Server settings with environment variables on Linux.

Run multiple SQL Server containers

Docker provides a way to run multiple SQL Server containers on the same host machine. Use this approach for scenarios that require multiple instances of SQL Server on the same host. Each container must expose itself on a different port.

::: moniker range="= sql-server-linux-2017 || = sql-server-2017"

The following example creates two [!INCLUDEsssql17-md] containers and maps them to ports 1401 and 1402 on the host machine.

::: zone pivot="cs1-bash"

docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' -p 1401:1433 -d mcr.microsoft.com/mssql/server:2017-latest
docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' -p 1402:1433 -d mcr.microsoft.com/mssql/server:2017-latest

::: zone-end

::: zone pivot="cs1-powershell"

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:2017-latest
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1402:1433 -d mcr.microsoft.com/mssql/server:2017-latest

::: zone-end

::: zone pivot="cs1-cmd"

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:2017-latest
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1402:1433 -d mcr.microsoft.com/mssql/server:2017-latest

::: zone-end

::: moniker-end

::: moniker range=">= sql-server-linux-ver15 || >= sql-server-ver15 "

The following example creates two [!INCLUDEsssql19-md] containers and maps them to ports 1401 and 1402 on the host machine.

::: zone pivot="cs1-bash"

docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' -p 1401:1433 -d mcr.microsoft.com/mssql/server:2019-latest
docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' -p 1402:1433 -d mcr.microsoft.com/mssql/server:2019-latest

::: zone-end

::: zone pivot="cs1-powershell"

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:2019-latest
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1402:1433 -d mcr.microsoft.com/mssql/server:2019-latest

::: zone-end

::: zone pivot="cs1-cmd"

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1401:1433 -d mcr.microsoft.com/mssql/server:2019-latest
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>" -p 1402:1433 -d mcr.microsoft.com/mssql/server:2019-latest

::: zone-end

::: moniker-end

Now there are two instances of SQL Server running in separate containers. Clients can connect to each SQL Server instance by using the IP address of the Docker host and the port number for the container.

::: zone pivot="cs1-bash"

sqlcmd -S 10.3.2.4,1401 -U SA -P '<YourPassword>'
sqlcmd -S 10.3.2.4,1402 -U SA -P '<YourPassword>'

::: zone-end

::: zone pivot="cs1-powershell"

sqlcmd -S 10.3.2.4,1401 -U SA -P "<YourPassword>"
sqlcmd -S 10.3.2.4,1402 -U SA -P "<YourPassword>"

::: zone-end

::: zone pivot="cs1-cmd"

sqlcmd -S 10.3.2.4,1401 -U SA -P "<YourPassword>"
sqlcmd -S 10.3.2.4,1402 -U SA -P "<YourPassword>"

::: zone-end

Upgrade SQL Server in containers

To upgrade the container image with Docker, first identify the tag for the release for your upgrade. Pull this version from the registry with the docker pull command:

docker pull mcr.microsoft.com/mssql/server:<image_tag>

This updates the SQL Server image for any new containers you create, but it doesn't update SQL Server in any running containers. To do this, you must create a new container with the latest SQL Server container image and migrate your data to that new container.

  1. Make sure you are using one of the data persistence techniques for your existing SQL Server container. This enables you to start a new container with the same data.

  2. Stop the SQL Server container with the docker stop command.

  3. Create a new SQL Server container with docker run and specify either a mapped host directory or a data volume container. Make sure to use the specific tag for your SQL Server upgrade. The new container now uses a new version of SQL Server with your existing SQL Server data.

    [!IMPORTANT] Upgrade is only supported between RC1, RC2, and GA at this time.

  4. Verify your databases and data in the new container.

  5. Optionally, remove the old container with docker rm.

Next steps

::: moniker range="= sql-server-linux-2017 || = sql-server-2017"

::: moniker-end

::: moniker range=">= sql-server-linux-ver15 || >= sql-server-ver15 "

::: moniker-end