Драйверы Microsoft SQL Server для PHP

Скачать драйвер PHP

Драйверы Microsoft для PHP for SQL Server — это расширения для PHP, которые позволяют читать и записывать данные в Microsoft SQL ядро СУБД из PHP-скриптов. Пакет поставляется с двумя драйверами, которые используют один и тот же драйвер Microsoft ODBC для SQL Server и используют одинаковые варианты подключения, так что вы можете выбрать API, подходящий для вашей кодовой базы:

  • SQLSRV предоставляет процедурный API (sqlsrv_*функции), адаптированный к функциям SQL Server.
  • PDO_SQLSRV реализует интерфейс PHP Data Objects (PDO), поэтому код, уже использующий PDO для других баз данных, может таргетировать SQL Server с минимальными изменениями.

Оба драйвера подключаются к База данных SQL Azure, SQL Database в Microsoft Fabric, Управляемый экземпляр SQL Azure, а также со всеми поддерживаемыми версиями и редакциями SQL Server (включая версии Express). Они используют потоки PHP для передачи больших бинарных и символьных значений без полной загрузки их в память.

Выберите начальную точку

Производственные базовые показатели для Azure SQL

Используйте этот фрагмент как отправную точку для производственного Azure SQL соединения с драйвером PDO_SQLSRV. Он считывает сервер и базу данных из переменных среды (например, из настроек приложения Служба приложений Azure), выполняет аутентификацию с помощью управляемой идентификации, включает безопасность транспортного уровня (TLS) с проверкой сертификата сервера, задаёт тайм-аут входа, достаточный для переключения при холодном запуске, и задаёт ConnectRetryCount и ConnectRetryInterval для устойчивости неактивных подключений SQL Server. Вспомогательные функции уровня приложения connectWithRetry и queryWithRetry применяют к начальному подключению и к каждому запросу ограниченную экспоненциальную задержку между повторами, а также отделяют временные ошибки подключения (требующие нового соединения) от временных ошибок запроса (при которых используется то же соединение).

Требуется версии PHP 8.0 и более поздние, расширение PDO_SQLSRV и драйвер Microsoft ODBC для версий SQL Server 17.3.1.1 и более поздних версий для Authentication=ActiveDirectoryMsi. Полный список поддерживаемых Authentication значений см. раздел «Подключение с помощью аутентификации Microsoft Entra».

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Этот фрагмент предназначен для групп автоматического переключения База данных SQL Azure и Управляемый экземпляр SQL Azure.

  • Driver={ODBC Driver 18 for SQL Server} закрепляет драйвер ODBC 18. Если на хосте также установлен ODBC 17, PDO_SQLSRV может привязаться к ODBC 17. Старые сборки 17.x отклоняют новые Authentication значения; например, Authentication=ActiveDirectoryMsi требуется ODBC 17.3.1.1 или более поздняя версия. См. значение Invalid, указанное для атрибута строка подключения 'Authentication'.

  • ConnectRetryCountи ConnectRetryInterval являются ключевыми словами ODBC строка подключения, которые обеспечивают устойчивость SQL Server к бездействующему соединению: драйвер прозрачно переподключает сломанное соединение в режиме простоя. Это отличается от механизма queryWithRetry на уровне приложения, который повторно выполняет инструкцию, завершившуюся сбоем из-за временной ошибки, например взаимоблокировки или превышения времени ожидания запроса. Эти два варианта дополняют друг друга, так что оставьте оба. Убедитесь, что LoginTimeout составляет не менее ConnectRetryCount * ConnectRetryInterval, чтобы сценарий переподключения в режиме простоя получил весь отведённый ему бюджет времени; в примере используется 90 секунд, чтобы учесть 5 × 15 секунд повторных попыток плюс запас для первоначального входа в систему при холодном переключении на резерв.

  • Дополняйте вызовы на уровне error_log() приложений драйверской диагностикой. Для PDO_SQLSRV установите pdo_sqlsrv.log_severity в php.ini (можно установить только при инициализации); для SQLSRV вызовите sqlsrv_configure("LogSubsystems", ...) во время выполнения. Для получения дополнительной информации см. раздел «Активность логирования».

    ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
; useful during triage but very chatty.
[pdo_sqlsrv]
pdo_sqlsrv.log_severity = 1

  • Для управляемой идентификации, назначаемой пользователем передайте идентификатор этой идентификации в качестве аргумента $username PDO (new PDO($dsn, $identityId, null, $options)). Используйте клиентский идентификатор идентичности в Служба приложений Azure или Azure Container Instance; в противном случае используйте его объектный идентификатор. Драйверы PHP наследуют это поведение от базового драйвера Microsoft ODBC для SQL Server; для получения дополнительной информации см. раздел «Использование Microsoft Entra ID с драйвером ODBC». PDO_SQLSRV отвергает UID в самой строке DSN, поэтому используйте параметр конструктора. Передача null в качестве пользователя (как в примере) приводит к выбору управляемого удостоверения, назначенного системой, для узла Azure. Для SQLSRV (процедурного) передайте UID массив опций соединения.

  • Задайте значение MultiSubnetFailover=true при подключении к прослушивателю группы отработки отказа, прослушивателю группы доступности или конечной точке экземпляра отказоустойчивого кластера. Включение этого параметра повышает производительность подключения как для слушателей групп доступности с одной подсетью, так и для слушателей групп доступности с несколькими подсетями. Для получения дополнительной информации см. раздел «Поддержка высокой доступности, восстановление после катастроф».

  • Для масштабирования чтения или читаемого вторичного элемента добавьте ApplicationIntent=ReadOnly к названию источника данных (DSN).

  • Для суверенных облаков, где сертификат Subject Alternative Name (SAN) не включает хост, к которому вы подключаетесь, добавьте HostNameInCertificate это в DSN (например, *.database.usgovcloudapi.net для Azure для государственных организаций).

  • Драйвер основан на базовом драйвере Microsoft ODBC для SQL Server для получения токенов. Управляемые потоки идентичности, принципа сервиса и токена доступа проходят через ODBC. Дополнительные сведения см. в разделе Использование Microsoft Entra ID с драйвером ODBC.

  • Для повышения безопасности и портативности между окружениями храните информацию о соединении вне вашего кода. Храните информацию о соединениях в системе конфигурации вашего приложения и используйте Azure Key Vault для чувствительных значений и централизованно управляемых настроек соединения.

  • Эквивалентное соединение SQLSRV использует sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) и возвращает ресурс. Схема повторных попыток та же: обработать возврат false от sqlsrv_connect, проверить SQLSTATE в sqlsrv_errors() и выждать паузу перед повторной попыткой. Для отработанного примера см. Шаг 4: Устойчивое подключение к SQL с помощью PHP.

  • Вспомогательные функции повторных попыток считывают $e->errorInfo[1] под защитой isset(). PDOException::$errorInfo объявляется как ?array и по умолчанию имеет значение null, поэтому защитная проверка возвращается к коду драйвера 0 и позволяет префиксу SQLSTATE 08 решать, следует ли повторить попытку.

Дополнительные сведения о каждой части этой конфигурации см. в следующей статье:

Каталог временных ошибок Azure SQL см. в разделе "Устранение временных ошибок подключения".

Ключевые особенности

  • Два API, один драйверный пакет: процедурный SQLSRV для SQL Server-первого кода или PDO_SQLSRV для портативного PDO-кода.
  • Поддержка широкой платформы: работает на Windows, Linux и macOS с поддерживаемыми версиями PHP.
  • Зашифрованные соединения: TLS-шифрованные соединения через Encrypt=true, при этом проверка серверного сертификата контролируется TrustServerCertificate.
  • Аутентификация Microsoft Entra ID: Безпарольные соединения с управляемой идентификацией, принципом сервиса и токена доступа, проходящими через базовый драйвер Microsoft ODBC для SQL Server.
  • Always Encrypted: шифрование на стороне клиента для конфиденциальных столбцов с необязательными безопасными анклавами для операций на месте.
  • Устойчивость соединения: встроенные повторные попытки для неактивных подключений с ConnectRetryCount и ConnectRetryInterval.
  • PHP-потоки: читать и записывать большие бинарные и символьные значения в виде потоков вместо загрузки их в память.
  • Широкая поддержка типов данных SQL Server: datetimeoffset, табличные параметры, nvarchar и Unicode с PDO::SQLSRV_ENCODING_UTF8.

Get started

Статья Description
Требования к системе Поддерживаются версии PHP, операционной системы и SQL Server.
Матрица поддержки Подробная матрица совместимости для выпусков драйверов PHP.
Скачайте драйверы Microsoft для PHP для SQL Server Ссылки для скачивания и файлы релиза.
Учебник по установке Linux и macOS Установите драйвер и его требования ODBC на Linux и macOS.
Загрузка драйверов Включите расширения в php.ini.
Начало работы с драйвером PHP SQL Сквозное пошаговое руководство, объединяющее четыре шага для начала работы.
Обзор PHP-драйвера SQL Что входит в комплект и когда выбирать SQLSRV или PDO_SQLSRV.

Настройка и подключение

Статья Description
Подключение к серверу Откройте подключение к экземпляру SQL Server из PHP.
Параметры подключения Полный справочник по ключевым словам соединения, значениям по умолчанию и их установке.
Подключение к базе данных Microsoft Azure SQL Подключите PHP-приложение к База данных SQL Azure.
Подключитесь к заданному порту Нацеливайтесь на нестандартный TCP-порт.
Организация пулов соединений Повторное использование ODBC-соединений во всех PHP-запросах.
Отключить несколько активных наборов результатов (MARS) Отключите MARS для совместимости.
Поддержка LocalDB Подключитесь к экземпляру SQL Server LocalDB.
Поддержка высокой доступности, восстановления после катастроф Прослушиватели групп доступности и отработка отказа в нескольких подсетях.
Устойчивость к простою соединения Автоматическое повторное подключение при прерванных холостых соединениях.

Authenticate

Статья Description
Подключитесь, используя аутентификацию Microsoft Entra Управляемая идентификация, субъект-служба, маркер доступа и потоки с паролем.
Подключитесь с помощью аутентификации SQL Server Используйте SQL-логин с именем пользователя и паролем.
Подключитесь с помощью проверка подлинности Windows Используйте интегрированную аутентификацию Windows на хостах, связанных с доменом.

Secure

Статья Description
Вопросы безопасности Модель угроз и глубокое руководство по защите для PHP-приложений.
Всегда шифруется с драйверами PHP Настройте шифрование на стороне клиента для конфиденциальных столбцов.
Всегда зашифровано с безопасными анклавами Обеспечьте выполнение расширенных операций с зашифрованными столбцами с использованием защищённых анклавов.

Получение и обновление данных

Статья Description
Руководство по программированию Сквозное руководство по программированию для обоих драйверов.
Сравнение функций исполнения Выберите правильную функцию выполнения для вашей нагрузки.
Прямое и подготовленное выполнение заявления (PDO_SQLSRV) Когда использовать прямое исполнение по сравнению с подготовленными заявлениями.
Извлечение данных Получайте строки, столбцы и потоковые значения.
Обновление данных Вставлять, обновлять и удалять строки.
Выполняйте параметризованные запросы Привязать параметры для защиты от SQL-инъекции.
Отправляйте данные в виде потока Транслируйте большие бинарные и символьные значения в SQL Server.
Выполнять транзакции Сгруппируйте операторы в атомарные транзакции.
Использование параметров с таблицными значениями Передайте TABLE параметр сохранённой процедуре.
Закажите тип курсора и выберите строки Выберите курсоры только вперёд, статические, динамические или клавишные курсоры.

Типы данных

Статья Description
Преобразование типов данных Как драйвер сопоставляет типы PHP на типы SQL Server.
Типы данных по умолчанию на SQL Server Тип SQL Server по умолчанию для каждого значения PHP.
Стандартные типы данных PHP Стандартный тип PHP для каждого типа столбца SQL Server.
Укажите типы данных SQL Server (SQLSRV) Переопределите тип SQL Server при привязке параметров.
Укажите типы данных PHP Переопределите тип PHP при извлечении.
Отправка и извлечение данных UTF-8 Используйте PDO::SQLSRV_ENCODING_UTF8 для поездок с Unicode туда и обратно.
Отправка и извлечение ASCII-данных на Linux и macOS Обрабатывайте ASCII туда и обратно на не-Windows-хостах.
Форматирование десятичных знаков и денег (SQLSRV) Форматируйте десятичные и денежные столбцы с помощью драйвера SQLSRV.
Форматирование десятичных чисел и денежных значений (PDO_SQLSRV) Форматируйте десятичные и денежные столбцы с помощью драйвера PDO_SQLSRV.
Настройки локальности вне системы Локализованные десятичные сепараторы и другие особенности местоположения.

Ошибки и диагностика

Статья Description
Обработка ошибок и предупреждений Обработка ошибок и предупреждений для обоих драйверов.
Настройка обработки ошибок и предупреждений (SQLSRV) Настройте то, как драйвер SQLSRV сообщает об ошибках и предупреждениях.
Обработка ошибок и предупреждений (SQLSRV) Проверьте ошибки, возвращаемые функциями SQLSRV.
Журналирование активности Включите логирование драйверов для диагностического захвата.

Развертывание и эксплуатация

Статья Description
Настройка производительности Управление соединениями, пакетирование, подготовленные выражения, курсоры, память и мониторинг на стороне сервера.
Troubleshooting Диагностируйте распространённые проблемы с установкой, подключением, запросом, типом данных, транзакциями и контейнерами.

Справочные материалы

Статья Description
Ссылка на API драйвера SQLSRV Все sqlsrv_* функции, параметры и возвратные значения.
Справочник по драйверу PDO_SQLSRV Методы PDO и PDOStatement, поддерживаемые драйвером PDO_SQLSRV.
Константы Константы, представленные драйверами, включая константы типов и кодирования.
Статья Description
Заметки о выпуске История каждой версии с новыми функциями, исправлениями ошибок, изменениями поддержки платформы и ссылками на скачивания.
О образцах кода в документации Конвенции, используемые в образцах кода в этом разделе.
Примеры кода для PHP-SQL-драйвера Полнофункциональные примеры приложений для SQLSRV и PDO_SQLSRV.
Поддерживающие ресурсы Сообщество и каналы поддержки.

Связанный контент

  • Last updated on