LINUX-MSSQL-BUILD.md

# Building sqlsrv & pdo_sqlsrv (.so) on Linux

Microsoft ships the MSSQL PHP drivers as **source through PECL**, so the `.so` must be compiled
against your exact PHP version. This is fast and repeatable. Example for **Debian/Ubuntu, x64**.

## 1. Install the Microsoft ODBC driver (runtime dependency)

```bash
# Debian/Ubuntu
curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
curl https://packages.microsoft.com/config/debian/12/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev
```

## 2. Install PHP build tooling

```bash
# replace 8.3 with your PHP minor version
sudo apt-get install -y php8.3-dev php-pear gcc g++ make
```

## 3. Build the extensions with PECL

```bash
# For PHP 8.1+ the latest 5.13.x works; for PHP 7.4/8.0 pin 5.10.1:
sudo pecl install sqlsrv pdo_sqlsrv
# or a pinned version:
#   sudo pecl install sqlsrv-5.10.1 pdo_sqlsrv-5.10.1   # PHP 7.4 / 8.0
#   sudo pecl install sqlsrv-5.12.0 pdo_sqlsrv-5.12.0   # PHP 8.1 / 8.2
#   sudo pecl install sqlsrv-5.13.3 pdo_sqlsrv-5.13.3   # PHP 8.3
```

The compiled `sqlsrv.so` and `pdo_sqlsrv.so` land in your `extension_dir`
(`php-config --extension-dir`).

## 4. Enable them

```bash
echo "extension=sqlsrv.so"     | sudo tee /etc/php/8.3/mods-available/sqlsrv.ini
echo "extension=pdo_sqlsrv.so" | sudo tee /etc/php/8.3/mods-available/pdo_sqlsrv.ini
sudo phpenmod sqlsrv pdo_sqlsrv
php -m | grep -i sqlsrv
```

## Version compatibility (msphpsql)

| Driver version | Supported PHP |
|----------------|---------------|
| 5.10.x         | 7.4 – 8.1     |
| 5.11.x         | 8.0 – 8.2     |
| 5.12.x         | 8.1 – 8.3     |
| 5.13.x         | 8.1 – 8.4     |

## Alpine Linux (musl)

```bash
apk add --no-cache unixodbc-dev php83-dev php83-pear gcc g++ make
# plus the msodbcsql18 musl package from Microsoft
pecl install sqlsrv pdo_sqlsrv
```