Connect to an instance

A connection string carries the sa password, so revealing one needs sqlservercluster/readSecrets. The Owner, Contributor and Databases Operator roles have it; Reader and Database Explorer do not. Every reveal is recorded in the instance's activity log.

Get the connection string

On the instance's Overview, under Access Details, choose Reveal next to Connection String. Copy copies it and Hide hides it again. It is an ADO.NET connection string:

Server=tcp:<instance>.<namespace>.svc.cluster.local,1433;Database=<database>;User Id=sa;Password=<password>;Encrypt=true;TrustServerCertificate=true

• The host is the instance's in-cluster name; <namespace> is the resource group's namespace on the cluster. A workload in the same resource group can also use the instance's name alone.
• Database is the initial database, or master when the instance was created without one.
• A value that contains ;, = or a quote is enclosed in double quotes.
• Encrypt=true makes the client encrypt the connection; TrustServerCertificate=true makes it accept the server's own certificate, which is not issued by a certificate authority.

.NET applications using Microsoft.Data.SqlClient take this form as it is. The API also returns a JDBC URL for Java clients and tools such as DBeaver:

jdbc:sqlserver://<instance>.<namespace>.svc.cluster.local:1433;databaseName=<database>;user=sa;password=<password>;encrypt=true;trustServerCertificate=true

With the CLI, which prints both forms, or with --raw only the ADO.NET one:

stsh sqlserver connstr my-sql -g my-resource-group
stsh sqlserver connstr my-sql -g my-resource-group --raw

Use it in a workload

The platform does not hand the connection string to your workloads by itself. Keep it in a vault and reference it from the workload:

1. Add the connection string as a secret in a vault — see Add a secret.
2. Reference the secret from the workload: for an app or a function see Add a secret reference, for a container instance see Container instances.

Only workloads in the instance's boundary can reach it — see Databases.

Connect from outside the cluster

1. On the instance's Configuration tab, open Networking & Security, turn on Enable External Access and save. The platform provisions a load balancer on port 1433.
2. On the Overview, External Address shows Provisioning… until the load balancer has an address, and then the address.
3. Choose Reveal next to External Connection String. It has the same form, with the load balancer's address as the host — or, when the platform has published the instance on an address of its own, that address and port.

With the CLI:

stsh sqlserver external-ip my-sql -g my-resource-group
stsh sqlserver connstr my-sql -g my-resource-group --external

To let only some networks in, choose Selected networks under Firewall in the same section and enter the ranges in Allowed CIDRs, separated by commas: 10.0.0.0/16, 192.168.1.0/24. The list applies to connections through the load balancer only, and only while external access is on.

Warning

Turning Enable External Access off again does not remove the load balancer: the instance stays reachable on its external address, although the portal no longer shows it. Leave external access off until you need it, and restrict it with Allowed CIDRs when you turn it on.

Logins other than sa

The platform gives out only the sa login. To give an application a login with fewer rights, create the login and its database user with a SQL Server client connected as sa, and store that login's connection string in the vault instead. The Data Explorer does not run CREATE LOGIN or CREATE USER statements — see What runs.