How To Install SQL Server on Mac using Docker and Azure Data Studio

Introduction

This guide explains how to install and run SQL Server on a Mac with Apple Silicon (M1, M2, M3, and M4) using Docker and Azure SQL Edge. Instead of using virtual machines or emulators, this method uses containers.

The guide also covers common mistakes and offers troubleshooting steps when needed.

Why Use Azure SQL Edge?

Microsoft Azure SQL Edge is designed for edge computing but is also a lightweight alternative to full SQL Server installations for development on macOS. Since Apple Silicon runs on ARM64 architecture, standard SQL Server images are incompatible, making Azure SQL Edge the best choice.

For more details, refer to the official Azure SQL Edge documentation.

Prerequisites

Ensure that you have the following installed on your Mac:

• Docker Desktop

• Azure Data Studio

• macOS Monterey or later

If Docker is not installed, follow the Docker installation guide.

Step 1: Install and Configure Docker Desktop

1. Download and install Docker Desktop from the Docker official site.

2. Open Docker Desktop, go to Settings > General, and ensure that "Use the virtualization framework" is enabled.

3. Verify that Docker is installed and running by executing the following command:

    docker --version
   

   Expected output:

    Docker version 24.xx.xx, build xxxxxx
   

4. If Docker is not running, restart your machine and ensure that the Docker service is started.

Step 2: Pull the Azure SQL Edge Image

To fetch the correct SQL Server image for Apple Silicon, run in Terminal:

docker pull mcr.microsoft.com/azure-sql-edge

Common Mistakes & Troubleshooting:

• Password Complexity Error: If the container fails to start, check that your password meets security requirements.

• Port Binding Error: If you get an error stating port 1433 is already in use, modify the mapping (-p 1434:1433) and connect using port 1434.

• Container Not Starting: Run docker logs azuresql to check logs for error messages.

Verify that the image is running:

Step 3: Create and Run the SQL Server Container

Run the following command to create and start an Azure SQL Edge container:

docker run -e 'ACCEPT_EULA=1' \
-e 'MSSQL_SA_PASSWORD=YourStrong!Passw0rd' \
-e 'MSSQL_PID=Developer' \
-p 1433:1433 --name azuresql -d mcr.microsoft.com/azure-sql-edge

// alternative command
docker run --cap-add SYS_PTRACE \
-e 'ACCEPT_EULA=1' \
-e 'MSSQL_SA_PASSWORD=StrongPass321' \
-e 'MSSQL_PID=Developer' \
-p 1433:1433 --name azuresqledge -d mcr.microsoft.com/azure-sql-edge

// Expected output
95b990b5bbeeb4b26e2edd9eb2ae479a145f166a454ee5f033c6cc9c4bb0eb48

(similar)

Explanation of Parameters:

• ACCEPT_EULA=1: Required to accept Microsoft’s SQL Server license agreement.

• MSSQL_SA_PASSWORD=YourStrong!Passw0rd: Specifies the system administrator (SA) password. Must be at least 8 characters, including uppercase, lowercase, numbers, and symbols.

• MSSQL_PID=Developer: Enables Developer Edition, which is free for development and testing.

  Here’s a breakdown of available values:

  • Developer: Fully featured, and free for development and testing only. Cannot be used in production.
  • Express: Free, lightweight version with feature limitations, suitable for small applications.
  • Standard: Paid edition with fewer features than Enterprise, used for mid-tier applications.
  • Enterprise: Paid, fully featured commercial edition for large-scale production workloads.
  • Evaluation: Free trial of the Enterprise Edition, expires after 180 days.

• -p 1433:1433: Maps SQL Server’s default port 1433 from the container to the host machine.

• --name azuresql: Assigns the container the name "azuresql".

• -d: Runs the container in detached mode (background process).

Common Mistakes & Troubleshooting:

• Password Complexity Error: If the container fails to start, check that your password meets security requirements.

• Port Binding Error: If you get an error stating port 1433 is already in use, modify the mapping (-p 1434:1433) and connect using port 1434.

• Container Not Starting: Run docker logs azuresql to check logs for error messages.

Verify that the container is running:

Step 4: Install and Connect via Azure Data Studio

1. Download Azure Data Studio from Microsoft's website.

2. Open Azure Data Studio and click New Connection.

3. Enter the following details:

   • Server: localhost

   • Authentication Type: SQL Login

   • User name: sa

   • Password: Use the password from Step 3.

4. Click Connect.

Common Mistakes & Troubleshooting:

• Login Failed: Ensure the correct password is being used and restart the container if necessary.

• Cannot Connect to Server: Confirm that the container is running with docker ps.

• Firewall or Security Blocking Connection: Run nc -zv localhost 1433 to check if the port is accessible.

Step 5: Verify SQL Server Installation

To confirm that SQL Server is running, execute the following SQL command in Azure Data Studio:

Expected output will confirm that Azure SQL Edge is installed and running.

Managing SQL Server Container

Once your SQL Server container is running, you may need to manage its lifecycle, including restarting, stopping, and removing the container. Below are key Docker commands to manage your SQL Server container efficiently.

Restart the Container

If you have stopped the container and need to restart it, use:

docker start azuresql

This will restart the container without requiring a new setup.

Stop the Container

To stop a running container, execute:

docker stop azuresql

Stopping the container preserves its data and configuration but halts SQL Server operations until restarted.

Remove the Container

If you need to delete the container completely (e.g., to free up resources or start fresh), run:

docker rm azuresql

Note: Removing the container deletes all databases and data unless you have mounted a volume for persistent storage.

View Running Containers

To check if your SQL Server container is active, use:

docker ps

This command lists all running containers along with their names, ports, and statuses.

To see all containers (including stopped ones), run:

docker ps -a

Additional Management Commands

For advanced container management, consider:

• View Logs:

    docker logs azuresql
  

  Useful for debugging SQL Server startup issues.

• Access SQL Server Command Line Interface (CLI):

    docker exec -it azuresql /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStrong!Passw0rd'
  

  Allows running SQL queries directly inside the container.

• Check Resource Usage:

    docker stats
  

  Displays real-time CPU and memory usage of running containers.

For more detailed container management, refer to the Docker documentation.

Conclusion

You have successfully installed and set up SQL Server on Mac (M1, M2, M3, M4) using Docker with Azure SQL Edge and connected it through Azure Data Studio. This setup enables SQL Server development and testing without needing a Windows machine.For further information, refer to the following official resources:

• Azure SQL Edge Documentation

• Azure Data Studio Guide

• Docker Reference