azuresql-db-connections

Reliable connections on the Azure SQL Database container (pooling + retry)

Make the app's database connections reliable with connection pooling and retry / transient-fault handling. This is the Azure SQL engine (Private Preview), not the SQL Server image.

Verified on 2026-09-05 against the container image sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest, reporting EngineEdition 5, Edition SQL Azure, build 12.0.2000.8. All five executable checks behind this skill passed: the engine identity, Msg 40508 for USE, a TCP session on the mapped port, and the two resource-governance dynamic management views returning nothing locally. Of the ten transient error numbers in the retry list below, nine are in this build's sys.messages and Msg 10929 is not. It stays in the list because it is a cloud resource-governance error the container has no reason to raise, and it is sourced from Microsoft Learn rather than from that run.

Why do this locally (local-to-cloud parity)

The local container rarely drops a connection, so it is tempting to skip pooling and retry. Do not. Azure SQL Database in the cloud throttles and drops connections during failovers, scaling, and load; a client with no retry surfaces those as hard errors. Build pooling and retry now, against the local container, and the same code survives in the cloud with no rewrite. For the full promote-to-cloud story see the azuresql-db-local-to-cloud skill.

Verify identity once running: SELECT SERVERPROPERTY('EngineEdition') returns 5 and SERVERPROPERTY('Edition') returns 'SQL Azure'. For full engine detail see the azuresql-db-container skill.

The container does not carry the throttling telemetry the cloud does, so do not write a local diagnostic against it. sys.dm_db_resource_stats and sys.dm_user_db_resource_governance are absent from this engine: OBJECT_ID returns NULL for both, and a query against either does not run at all here. Their absence is not evidence that the cloud does not throttle. It is the reason the retry policy below has to be built without being able to provoke the fault locally.

The engine and the connection contract

• Image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest (x64 / linux/amd64, Private Preview registry). Sign in first: docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io with the shared pull-only credentials from https://aka.ms/sqldbcontainerpreview-signup (they may rotate). On a non-x64 host add --platform linux/amd64 (Docker) or platform: linux/amd64 (compose).
• Do NOT use mcr.microsoft.com/mssql/server (the SQL Server image).
• Required env: ACCEPT_EULA=Y and a complex MSSQL_SA_PASSWORD (example literal: YourStr0ng_Passw0rd). The engine listens on 1433.
• The engine does NOT auto-create databases. CREATE DATABASE appdb on a master connection first. Do not USE to switch databases: a user-database session returns Msg 40508. Select the database in the connection string (Database=appdb).
• Apps read one env var, SQL_CONNECTION_STRING. Strings use User Id= / Password= / Database= and TrustServerCertificate=true. sqlcmd uses -C.

Start the container and provision appdb

HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"

The canonical string the app consumes (replace 1433 with the chosen HOST_PORT if 1433 was occupied):

Server=localhost,1433;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true

Pooling: reuse connections, do not reopen per query

• Keep pooling on (it is on by default in most drivers) and let one pool serve the app.
• Set a bounded Max Pool Size (default 100 in .NET) so a spike cannot open unlimited connections. Size it to real concurrency, not a guess.
• A small Min Pool Size keeps a few connections warm and cuts cold-start latency.
• One connection string means one pool. Do not build strings dynamically per request (each distinct string is a separate pool) and do not open a fresh, unpooled connection per call.
• Always close/dispose connections (or use using / with / context managers) so they return to the pool instead of leaking.

Retry: only for transient faults, with backoff

Retry only a transient fault: throttling, a brief failover, a dropped idle connection. In Azure SQL these arrive as specific error numbers: 40501 throttling, 40613 database unavailable, 49918/49919/49920 busy, 4060, 10928, 10929, 40197, 233, plus connection-timeout and broken-pipe socket errors.

• Retry only transient errors. Retrying a non-transient error (login failure 18456, syntax error, constraint violation, permission denied) just fails slower and hides the real bug.
• Use exponential backoff with a cap and a small jitter, and a bounded attempt count (for example 5 attempts). Do not hammer a throttled server.
• Non-idempotent writes: a retry can double-apply an INSERT that committed before the connection dropped. Use client-generated keys, MERGE, or a transaction the retry re-runs as a whole. EF Core's execution strategy handles this when the work goes through its Execute/transaction API.
• Prefer a framework retry policy over hand-rolled loops where one exists (EF Core EnableRetryOnFailure for .NET). Hand-roll only for raw drivers.

Per-stack

Open references/retry-snippets.md when you are wiring one of these stacks; it carries copy-pasteable pooling config and transient-only retry for each:

• .NET (Microsoft.Data.SqlClient): pooling keywords (Max Pool Size, Min Pool Size, Pooling=true) and connection-string retry keywords (ConnectRetryCount, ConnectRetryInterval); plus EF Core EnableRetryOnFailure (the SqlServer execution strategy).
• Node (mssql / tedious): pool config (max / min / idleTimeoutMillis) and a transient-error retry wrapper.
• Python (pyodbc): connection reuse and a tenacity retry decorator that retries only transient ODBC errors.

Keep the single SQL_CONNECTION_STRING contract: pooling and retry are tuned in code and in driver-specific keywords, not by inventing new env vars.

Validation rules

• Retry fires only on transient errors; non-transient errors (auth, syntax, constraint) surface immediately.
• Retry uses bounded attempts with exponential backoff, and non-idempotent writes are made safe to re-run (keys, MERGE, or a retriable transaction).
• Pooling is on with a bounded Max Pool Size; connections are disposed and returned to the pool, never opened per query.
• One connection string / one pool; the app still reads a single SQL_CONNECTION_STRING.
• Runs against the engine image with EngineEdition 5; appdb was created on a master connection before the app connected.
• If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the azuresql-db-feedback skill and offer to file a report.
• When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

Do not

• Do not retry non-transient errors (auth, syntax, constraint); they will just fail slower.
• Do not retry non-idempotent writes without idempotency (keys, MERGE, or a retriable transaction).
• Do not set an unbounded pool; do not open a new connection per query instead of pooling.
• Do not invent extra env vars; keep the single SQL_CONNECTION_STRING contract.
• Do not write a local throttling diagnostic against sys.dm_db_resource_stats or sys.dm_user_db_resource_governance; neither view exists on this engine.
• Do not use the mcr.microsoft.com/mssql/server SQL Server image, and do not call a non-x64 host "supported".

References

• references/retry-snippets.md: copy-pasteable pooling config and transient-only retry for .NET (Microsoft.Data.SqlClient + EF Core EnableRetryOnFailure), Node (mssql/tedious pool + retry wrapper), and Python (pyodbc reuse + tenacity decorator). Read the section for your stack.

Staying current

Authoritative, version-pinned references for the tools this skill uses (read the one you need):

• SQL Server connection pooling (ADO.NET): how pooling works and the tuning keywords.
• EF Core connection resiliency: EnableRetryOnFailure and execution strategies.
• SqlConnection connection string keywords: the full keyword table including pooling and retry.

If the Microsoft Learn MCP server is configured, use mcp__microsoft-learn__microsoft_docs_search or mcp__microsoft-learn__microsoft_docs_fetch to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative.