Connect to Azure SQL Database from Your Mac

by

If you’ve set up an Azure SQL Database, you’ll almost certainly want to connect to it at some point. You’ll probably want to connect to it, and then run a bunch of SQL queries, just like you would do if you had SQL Server installed locally or across the network.

Fortunately, connecting to Azure SQL Database is relatively straight forward. Let’s look at two options for connecting via a Mac: SQL command line tools and VS Code.

Prerequisite

I’ll assume you’ve already set up a server and SQL database in your Azure portal.

And I’ll assume you’ve already got your login credentials (if needed) and you’ve configured your networking rules to allow access to your machine/IP address.

On that last point, if you haven’t (or you’re not sure whether you have or haven’t), you will want to go into your server and check your server’s Networking settings and ensure that it grants you access.

For example:

  1. Click on your server, then click “Show network settings”. Alternatively, you can navigate to them using the menu.
  2. Once there, under “Public Access” select “Selected networks”.
  3. Under “Firewall rules” add your IP address (or a range of IPs).

That assumes you want to use the “Public Access” option. If you have another setup in mind, use that option and configure it accordingly.

When you connect to an Azure SQL database, you’ll need to have details, such as the server, the database name, etc. You can get most of these details from the portal itself.

The steps below use SQL Authentication method, and so this method requires providing the username and password.

Option 1: Using Command Line Tools (sqlcmd)

For the command line option, we’ll use sqlcmd (which is part of mssql-tools). Basically, mssql-tools includes sqlcmd and bcp (which is a bulk copy program).

Install SQL Server Command Line Tools

If you don’t already have sqlcmd installed, install it via mssql-tools:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

This installs version 18. By the time you read this it’s possible that a newer version is available. You can therefore use the newer version number instead of 18. To get the latest version number (as well as installation instructions), try checking the Microsoft’s help page for installing the command line tools.

After installation, you can check that everything is OK by running the following:

sqlcmd '-?'

This should return details about the program, including its version number, as well as help on usage. If you see a different version number, it’s likely that you already had an earlier version installed outside of Homebrew.

If this happens, you can update your shell’s PATH to prioritize Homebrew binaries. For zsh, add this to your ~/.zshrc:

export PATH="/opt/homebrew/bin:$PATH"

Then reload your shell:

source ~/.zshrc

Connect and Query Your Database

Test your connection:

sqlcmd -S yourserver.database.windows.net \
       -d dev-test-db \
       -U 'yourusername' \
       -P 'yourpassword' \
       -N -C \
       -Q "SELECT @@VERSION"

I enclosed the username and password in quotes here, because this prevents any special characters from messing things up. I used backslashes in order to format the command across multiple lines. You can omit these if you want to condense it to a single line.

Also, if you’re concerned about security (e.g., password in terminal history), consider omitting the password option altogether. When you do this you’ll be prompted for the password each time you connect.

If you get an error like this when you run the above command:

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Login timeout expired.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : TCP Provider: Timeout error [258]. .
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Unable to complete login process due to delay in login response.

It could simply be that your database is currently paused. If you jump over to your portal, you might be quick enough to see it change status to “Resuming” and then “Online”. If this happens, wait a few seconds and run the command again.

Running the command again (once the database is online) should return something like this:

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Microsoft SQL Azure (RTM) - 12.0.2000.8 
	Jul  3 2025 16:52:14 
	Copyright (C) 2025 Microsoft Corporation
                                                                                                                                                                                                  

(1 rows affected)

If you get a similar message it means that you successfully connected to your Azure SQL database.

Option 2: Using VS Code

VS Code is a good option if you prefer to use a graphical user interface (GUI). This provides a graphical view of your database, where you can see the database and its objects in an expandable tree menu.

Install Required VS Code Extensions

If you haven’t already installed the SQL Server (mssql) extension, go ahead and do that now.

Open VS Code and do this:

  1. Go to Extensions (Cmd+Shift+X)
  2. Search for “SQL Server (mssql)”
  3. Install the official Microsoft extension
Screenshot of the SQL Server (mssql) extension in VS Code

Connect to Your Database

Now that the SQL Server (mssql) extension is installed, let’s go ahead and connect to Azure.

  1. Open Command Palette: Press Cmd+Shift+P
  2. Add Connection: Type “MS SQL: Add Connection” and select it.

This should eventually result in the “Connect to Database” screen appearing:

Screenshot of the "Connect to Database" screen

Go ahead and fill in the connection details. For example:

  • Profile Name: Give it a name (e.g., “Azure Dev DB”)
  • Connection Group: It’s fine to leave it at the default (Connection Group is just a way to organize your saved connections within the SQL Server extension in VS Code).
  • Input type: Parameters
  • Server name: yourserver.database.windows.net
  • Trust server certificate: Leave it unchecked.
  • Authentication Type: Select “SQL Login”
  • User name: Your admin username
  • Password: Your admin password
  • Save Password: Choose “Yes”
  • Database name: dev-test-db
  • Encrypt: Strict

You may need to use different settings if you have a reason to do so (for example, if you use a different Authentication type).

Once done, click “Connect”.

Once connected, you should be able to see the Azure connection in the Connections pane in VS Code:

Screenshot of VS Code's "Connections" pane, with a connection to our Azure SQL database

Run Queries

You can now write queries agains your Azure SQL Database.

To run a query, right click on the Azure database and select “New Query”:

Screenshot of the "New Query" option

That opens a new query tab. In the query tab, run a simple SQL query to test it out.

For example:

SELECT @@VERSION as SQLVersion;

To run the query, click the triangular “Execute Query” button at the top.

Here’s what I got:

Screenshot of the query tab and result

And that’s it. You have now connected to your Azure SQL database.