Linux 下透過 FreeTDS 連線 Microsoft SQL Server 完整指南

Linux 下透過 FreeTDS 連線 Microsoft SQL Server 完整指南

在 Linux 環境連接 SQL Server，標準方案是安裝 FreeTDS (開源 TDS 協定實現) 搭配 unixODBC，再由 PHP 的 pdo_dblib 或 pdo_sqlsrv (官方驅動) 介接。本文整理完整編譯安裝與設定步驟。

1. 安裝 FreeTDS + unixODBC (編譯安裝)

# 依賴套件
yum install -y gcc make automake autoconf libtool openssl-devel

# 下載原始碼
wget ftp://ftp.freetds.org/pub/freetds/stable/freetds-1.3.20.tar.gz
tar -xzf freetds-1.3.20.tar.gz
cd freetds-1.3.20

# 編譯安裝 (支援 TDS 7.4 / 8.0 對應 SQL Server 2012+)
./configure --prefix=/usr/local/freetds \
            --with-openssl=/usr/include/openssl \
            --enable-msdblib \
            --with-tdsver=7.4
make
make install

# 設定 freetds.conf
cat > /usr/local/freetds/etc/freetds.conf <<'EOF'
[global]
    tds version = 7.4
    client charset = UTF-8
    text size = 64512

[mssql]
    host = 192.168.1.100
    port = 1433
    tds version = 7.4
EOF

# 測試連線
/usr/local/freetds/bin/tsql -S mssql -U sa -P 'password'

2. 安裝 unixODBC 並註冊 FreeTDS 驅動

yum install -y unixODBC unixODBC-devel

# 註冊驅動
odbcinst -i -d -f - <<'EOF'
[FreeTDS]
Description = FreeTDS Driver for SQL Server
Driver = /usr/local/freetds/lib/libtdsodbc.so
Setup = /usr/local/freetds/lib/libtdsS.so
FileUsage = 1
CPTimeout = 5
CPReuse = 5
EOF

# 設定 DSN (系統級)
odbcinst -i -s -l -f - <<'EOF'
[MSSQL]
Driver = FreeTDS
Server = 192.168.1.100
Port = 1433
Database = testdb
TDS_Version = 7.4
ClientCharset = UTF-8
EOF

# 測試 ODBC
isql -v MSSQL sa 'password'

3. PHP 安裝 pdo_dblib (基於 FreeTDS)

# PHP 原始碼編譯時加入
./configure --with-pdo-dblib=/usr/local/freetds ...
# 或安裝套件
yum install -y php-pdo-dblib  # (RHEL/CentOS 需啟用 EPEL + remi)
# Ubuntu
apt install -y php-sybase  # 內含 pdo_dblib

4. PHP 連線測試 (PDO_DBLIB)

<?php
$dsn = "dblib:host=192.168.1.100:1433;dbname=testdb;charset=utf8";
$user = "sa";
$pass = "password";

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);
    $stmt = $pdo->query("SELECT @@VERSION AS version");
    print_r($stmt->fetch());
} catch (PDOException $e) {
    die("連線失敗: " . $e->getMessage());
}
?>

5. 現代替代：Microsoft 官方驅動 (pdo_sqlsrv)

FreeTDS 為社群反向工程，功能有限 (不支援 Always Encrypted、TVP、UTF-16 等)。生產環境**強烈建議**使用 Microsoft 官方 pdo_sqlsrv + msodbcsql18：

# 1. 安裝 Microsoft ODBC Driver 18
curl https://packages.microsoft.com/config/rhel/9/prod.repo > /etc/yum.repos.d/mssql-release.repo
ACCEPT_EULA=Y yum install -y msodbcsql18 unixODBC-devel

# 2. 安裝 PHP sqlsrv/pdo_sqlsrv
pecl install sqlsrv pdo_sqlsrv
echo -e "extension=sqlsrv.so\nextension=pdo_sqlsrv.so" > /etc/php.d/30-sqlsrv.ini

# 3. DSN 格式
$dsn = "sqlsrv:Server=192.168.1.100,1433;Database=testdb;Encrypt=yes;TrustServerCertificate=no";

6. 常見問題排查

• 字元集亂碼：確保 FreeTDS client charset = UTF-8、資料庫欄位為 NVARCHAR、PHP 連線 DSN 含 charset=utf8。
• TDS 版本不符：SQL Server 2008 用 7.3，2012+ 用 7.4，若連線失敗嘗試調整 tds version。
• 防火牆/端口：確認 1433/tcp 通訊正常，telnet ip 1433 測試。
• SSL/TLS：官方驅動預設要求加密，FreeTDS 需編譯 --with-openssl 並設定 Encrypt=yes。