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

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

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

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

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

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

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

Этот пример PDO_SQLSRV считывает сервер и базу данных из переменных среды и соединяется с управляемой идентификацией. Он формирует имя источника данных (DSN) и поддерживает систему безопасности транспортного уровня (TLS) с валидацией сертификатов. Читайте эти значения из доверенной конфигурации приложения, а не из параметров веб-запроса. Запустите программу на хосте с конечной точкой управляемой идентификации после предоставления этой идентификации доступа к базе данных.

Вспомогательные функции делают до трёх попыток подключиться или выполнить запрос только для чтения при возникновении одной из перечисленных ошибок. Они ждут дольше между попытками — это паттерн повтора, называемый экспоненциальным отступлением. Если ошибка запроса требует нового соединения, помощник запроса выдает исключение для обработки вызывающего кода.

Используйте поддерживаемую версию PHP, расширение PDO_SQLSRV и Microsoft ODBC Driver 18 для SQL Server. Для поддерживаемых значений аутентификации см. раздел Connect using Microsoft Entra authentication. Не используйте помощник запроса для записи или многооператорных транзакций без разработки специфической для приложения политики повторных попыток: ошибка не всегда подскажет, была ли запись коммитирована.

<?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];

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * 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);
            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');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
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, RETRYABLE_READ_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.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$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,
    $databaseValue
);

$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 name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Используйте эти настройки для групп отработки отказа База данных SQL Azure и Управляемый экземпляр SQL Azure.

  • Driver={ODBC Driver 18 for SQL Server} выбирает ODBC Driver 18 явно, а не полагается на обнаружение драйверов. Установите его перед запуском примера.

  • Установите SQL_DATABASE на фактическое имя базы данных. Программа удваивает закрывающие скобки и заключает имя в фигурные скобки перед размещением в DSN. Escapeing не даёт особым символам в названии изменить то, как драйвер считывает настройки соединения.

  • ConnectRetryCount и ConnectRetryInterval управляют устойчивостью неактивного подключения ODBC. Тайм-аут запроса в команде ограничивает восстановление во время выполнения. С 30-секундным тайм-аутом запроса ODBC может остановиться, не исчерпав все пять попыток повторного подключения. LoginTimeout=90 Контролирует установление соединения, а не бюджет восстановления. Помощник на уровне приложения повторяет выбранные ошибки сервера; он не повторяет тайм-аут запроса и не воспроизводит частично полученные результаты.

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

    ; 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 вместо встраивания имени пользователя в DSN. Передача null в качестве пользователя (как в примере) приводит к выбору управляемого удостоверения, назначенного системой, для узла Azure. Для SQLSRV (процедурного) передайте UID массив опций соединения.

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

  • Для горизонтального масштабирования чтения или доступной для чтения вторичной реплики добавьте ApplicationIntent=ReadOnly в DSN.

  • Используйте конечную точку, предоставляемую вашим SQL-сервисом, включая его облачно-специфическую область. Исследуйте несоответствия имён сертификатов, а не отключайте проверку сертификатов. Используйте HostNameInCertificate только тогда, когда знаете ожидаемое имя сертификата для этой конечной точки.

  • ODBC получает токены для управляемой идентичности и аутентификации субъекта-службы. С AccessTokenпомощью , ваше приложение получает токен и передаёт его водителю; ODBC не приобретает его за вас. Дополнительные сведения см. в разделе Использование Microsoft Entra ID с драйвером ODBC.

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

  • С помощью SQLSRV задайте параметры соединения в массиве, передаваемые в sqlsrv_connect(). Проверьте наличие обратного false и осмотрите sqlsrv_errors() её, прежде чем решать, стоит ли пробовать снова. Устанавливайте тайм-ауты операторов отдельно с помощью QueryTimeout. Устойчивость соединения в простое демонстрирует повторное подключение ODBC, а не повторный цикл на уровне приложения.

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

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

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

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

  • Два PHP-API: SQLSRV предоставляет процедурные функции. PDO_SQLSRV реализует PDO. Установите либо расширение, либо оба варианта.
  • Поддержка широкой платформы: работает на Windows, Linux и macOS с поддерживаемыми версиями PHP.
  • Зашифрованные соединения: TLS-шифрованные соединения через Encrypt=true, при этом проверка серверного сертификата контролируется TrustServerCertificate.
  • Аутентификация Microsoft Entra ID: Управляемые удостоверения, субъект-служба и внешне полученные токены доступа через базовый драйвер Microsoft ODBC для SQL Server. Управляемое удостоверение не использует пароли; ActiveDirectoryServicePrincipal использует клиентский секрет.
  • Always Encrypted: Шифруйте чувствительные столбцы на клиенте с защищёнными анклавами для поддерживаемых операций с зашифрованными данными.
  • Устойчивость соединения: встроенные повторные попытки для неактивных подключений с ConnectRetryCount и ConnectRetryInterval.
  • PHP-потоки: Отправляйте большие бинарные и символьные значения из параметров потока через любой из API. Используйте SQLSRV для потокового извлечения.
  • Широкая поддержка типов данных 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.
Быстрый старт: подключитесь и отправьте запросы с помощью драйверов Microsoft для PHP Проверьте расширения, настройте соединение и выполните тот же параметризованный запрос с помощью SQLSRV или PDO_SQLSRV.
Обзор 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 или Kerberos на Linux и macOS.

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 Задайте опцию CharacterSet SQLSRV или атрибут PDO::SQLSRV_ATTR_ENCODING PDO_SQLSRV.
Отправка и извлечение 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.
Поддерживающие ресурсы Сообщество и каналы поддержки.

Запрашивание функции

Чтобы запросить новую функцию, создайте запрос в репозитории Microsoft Drivers for PHP for SQL Server GitHub repository.

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

  • Последнее обновление: