Incorrect documentation about when SQL Server is ready

[SimeonStoykovQC]

The following "Quickstart: Run SQL Server container images with Docker" docs suggest that it can be determined when SQL Server is ready to accept connections by checking the status of the Docker container:

If the STATUS column shows a status of Up, then SQL Server is running in the container and listening on the port specified in the PORTS column.

However, from my experiments, this is not true. In other words, even when the STATUS columns shows a status of Up, SQL Server is not ready to process commands.

Setup

OS: OSX Big Sur 11.4

You need two terminals. Terminal 1 will run logic that will try to connect to the SQL Server instance as soon as the container status is UP, and Terminal 2 will be used to start the docker container.

Terminal 1

Connecting to the SQL Server is done through Python and SQLAlchemy (free TDS driver). Thus you need the following dependencies installed:

sqlalchemy
freetds
pyodbc

After you have the above installed in your environment, run the following command:

until [[ $(docker ps --filter "name=mssql" --filter "status=running" -q | wc -l) -eq 1 ]]; do echo 'Waiting for status UP...' ; done; python -c 'import sqlalchemy as sa; sa.engine.create_engine(r"mssql+pyodbc://sa:Pass123#@127.0.0.1:1433/tempdb?driver=libtdsodbc.so").connect()'

This will:

1. Wait until the container with name mssql has status running/UP;
2. Try to connect to the database.

Terminal 2

Run the SQL Server inside a container:

docker run \
  -e "ACCEPT_EULA=Y"
  -e "MSSQL_SA_PASSWORD=Pass123#"
  -e "MSSQL_USER=sa"
  -p 1433:1433
  --name=mssql
  --rm -it mcr.microsoft.com/azure-sql-edge

Result

You should see that Terminal 1 exits the until loop and tries to connect to SQL Server as soon as the SQL Server container is started in Terminal 2. It then fails with something like:

sqlalchemy.exc.OperationalError: (pyodbc.OperationalError) ('08001', '[08001] [FreeTDS][SQL Server]Unable to connect to data source (0) (SQLDriverConnect)')

If you wait a bit (~10 seconds) and fire the same command in Terminal 1 again, it connects successfully (prints nothing).

[waclawkusnierczykqc]

Very well done, thank you for the write-up!

[amvin87-zz]

Thank you @SimeonStoykovQC! Yeah we can add further detail to that line in the document to avoid the confusion and bring clarity:

If the STATUS column shows a status of Up, then SQL Server is running in the container and listening on the port specified in the PORTS column. It will be ready for connection, once the SQL Server errorlogs display the message " SQL Server is now ready for client connections. This is an informational message; no user action is required" You can review the SQL Server errorlog inside the container using the command: "podman exec -t sqlrhel cat /var/opt/mssql/log/errorlog | grep connection"

If the STATUS column for your SQL Server container shows Exited, see Troubleshooting SQL Server Docker containers.

@VanTo can you please help make this edit in the document

[SimeonStoykovQC]

Thanks @amvin87 for the quick response. This correction looks good to me.

On a related note, looking for a specific line inside the log might be a bit fragile. Having this documented certainly helps since now this exact string has been stamped with a special meaning, but there is still the danger of it being changed in a future release. Thus I was wondering if there is a more reliable way to provide such functionality to the user? For example, you could raise a "flag" that the user of the container can check, and searching for this string in the logs could be an implementation detail on your side. If this is not the right place to discuss, I am happy to move to a new issue.

Thanks in advance.

[VanMSFT]

#assign:VanMSFT

[VanMSFT]

#assign:VanMSFT

[VanMSFT]

Hey @WilliamAntonRohm - Can you please help assign this to @VanMSFT and @rwestMSFT and then close this Issue? We've taken care of this. Thanks!

[WilliamAntonRohm]

@VanMSFT -- Van, thank you for asking & I would, but I don't have write perms in this repo.