Install or Update sqlpackage on a Mac via Zip (No .NET SDK Needed)

This guide explains how to install or update sqlpackage on macOS using the direct download (.zip) method. This approach avoids installing the full .NET SDK, which can be overkill if you only need the sqlpackage command-line tool. It includes the necessary steps for installation/update and handling macOS Gatekeeper security prompts for the newly extracted files.

This guide assumes you want to install sqlpackage into a directory named sqlpackage within your home directory (~/sqlpackage). If you choose a different location (e.g., /usr/local/sqlpackage), please adjust the paths in the commands accordingly.

Prerequisites

You are comfortable using the Terminal application on macOS.
You know how to download files from the internet.

Installation / Update Steps

Whether installing for the first time or updating an existing zip-based installation, the steps are largely the same.

Download the Latest Version:
- Navigate to the official Microsoft sqlpackage download page in your web browser (a web search for “Download sqlpackage Microsoft” should find it).
- Download the latest .zip archive suitable for macOS (often labeled for Linux/macOS). It will likely be saved to your ~/Downloads folder. Note the filename.
Remove Old Version (If Updating):
- If you are updating an existing installation in ~/sqlpackage, open the Terminal application and remove the old directory first.
- Warning: This command permanently deletes files. Double-check the path is correct before running. Skip this step if installing for the first time.
```
# Adjust path if your installation isn't in ~/sqlpackage
rm -rf ~/sqlpackage
```
Extract the New Version:
- Open Terminal.
- Navigate to the directory where you downloaded the new .zip file:
```
cd ~/Downloads
```
- Create the installation directory (this is safe even if updating, as we removed the old one):
```
mkdir ~/sqlpackage
```
- Extract the contents of the new .zip archive into this directory. Remember to replace sqlpackage-*.zip with the actual filename you downloaded:
```
# Example: unzip sqlpackage-osx-x64-170.0.94.3.zip -d ~/sqlpackage
unzip sqlpackage-*.zip -d ~/sqlpackage
```
Set Execute Permissions:
- Grant execute permission to the main sqlpackage executable file within the new directory:
```
chmod +x ~/sqlpackage/sqlpackage
```
Handle macOS Gatekeeper:
- macOS security (Gatekeeper) will likely prevent the newly extracted files from running initially because they came from a downloaded archive.
- To avoid multiple security prompts for sqlpackage and its components, run the following command once to remove the quarantine attribute from all files in the installation directory:
```
xattr -r -d com.apple.quarantine ~/sqlpackage
```
- This command recursively (-r) deletes (-d) the com.apple.quarantine attribute, effectively telling macOS you trust the contents of this specific folder.
Add to PATH (Recommended for Convenience):
- To run sqlpackage from any terminal location without typing the full path, add its directory to your shell’s PATH.
- Edit your shell’s configuration file (usually ~/.zshrc for modern macOS):
```
nano ~/.zshrc
```
- Add this line at the very end of the file:
```
export PATH="$PATH:$HOME/sqlpackage"
```
- Save the file (Ctrl+O, Enter) and exit (Ctrl+X).
- Apply the changes to your current terminal session (or open a new terminal window):
```
source ~/.zshrc
```
- (Note: If you were updating and ~/sqlpackage was already in your PATH, you can skip this step, but verifying doesn’t hurt).
Verify the Installation / Update:
- Confirm that sqlpackage runs correctly and check the version:
```
sqlpackage /version
```
- The output should display the version number corresponding to the .zip file you just installed.

Important Notes

Installation Path: If you chose an installation directory other than ~/sqlpackage, ensure you replaced ~/sqlpackage in all commands above with your chosen path.
Admin Rights (sudo): If your chosen installation directory is in a system location like /usr/local/sqlpackage, you might need to prefix the rm, mkdir, unzip, chmod, and xattr commands with sudo and enter your administrator password.

You have now successfully installed or updated sqlpackage using the zip file method, without needing the full .NET SDK!