Строки соединения для mssql-python

Драйвер mssql-python поддерживает следующие ключевые слова строка подключения при подключении к SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database в Microsoft Fabric.

Синтаксис строки подключения

Соединительные строки используют пары ключ-значение с точкой с запятой:

keyword1=value1;keyword2=value2;...

Значения обмотки, содержащие специальные символы (точку с запятой, знаки равенства или завитые скобки) в завитых скобах:

PWD={my;complex=password}

Чтобы включить литеральную замыкающую распорку в значение, используйте две замыкающие скобы (}}):

PWD={password}}with}}brace}

Основные примеры соединений

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

SQL Server с аутентификацией Microsoft Entra (рекомендуемо)

В этом примере используется ActiveDirectoryDefault, который пробует несколько источников учетных данных (Azure CLI, переменные среды, управляемая идентичность) по порядку. Пароль не хранится в коде:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server с SQL-аутентификацией

Используйте SQL-аутентификацию только для локальной разработки против инстанса SQL Server, которым вы управляете. Учетные данные встроены в строка подключения, поэтому храните их в переменных окружения или файле.env, а не в исходном коде:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL with Microsoft Entra authentication

Строка строка подключения для База данных SQL Azure совпадает с SQL Server. ActiveDirectoryDefaultработает в локальной разработке, контейнерах и средах, размещённых на Azure, без изменений кода:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Используйте аргументы по ключевым словам

Вы можете передавать параметры соединения в виде аргументов ключевых слов вместо или в дополнение к строка подключения. Аргументы ключевых слов избегают скрытых ловушек строка подключения assembly. Пароли со специальными символами, такими как @, ;, {, или } не требуют обертки curly-brace при передаче в качестве аргументов по ключевым словам:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Сравните с строка подключения assembly, где пароль @ должен быть обёрнут:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Драйвер объединяет аргументы ключевых слов в строка подключения после нормализации. Если аргумент ключевого слова совпадает с параметром, уже входящим в строка подключения, аргумент ключевого слова приобретает приоритет и переопределяет значение строка подключения:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

Следующий пример сочетает строка подключения с аргументами ключевых слов:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Ключевые слова в строке подключения

Сервер и база данных

Укажите целевой экземпляр SQL Server и базу данных для соединения.

Keyword	Псевдонимы	По умолчанию	Описание
`Server`	`addr`, `address`	Нет	Имя хоста, IP-адрес или именованный экземпляр SQL Server. Для именованных экземпляров используйте `server\instance`. Для Azure SQL используйте `server.database.windows.net`. Чтобы указать порт, используйте `server,port`.
`Database`	Нет	Нет	Имя базы данных для подключения.

Authentication

Предоставьте учетные данные для SQL-аутентификации или укажите режим аутентификации Microsoft Entra. Для вариантов без пароля см. режимы аутентификации Microsoft Entra.

Keyword	Псевдонимы	По умолчанию	Описание
`UID`	`uid`	Нет	Имя пользователя для SQL-аутентификации.
`PWD`	`pwd`	Нет	Пароль для SQL-аутентификации.
`Trusted_Connection`	`trusted_connection`	`no`	Используйте интегрированную аутентификацию Windows. Чтобы включить, установите значение `yes`.
`Authentication`	`authentication`	Нет	Режим аутентификации Microsoft Entra. См. проверку подлинности Microsoft Entra.

Шифрование и безопасность

Все подключения используют Encrypt=yes по умолчанию. Для большинства приложений по умолчанию достаточно. Используйте strict его только если ваш экземпляр SQL Server поддерживает TDS 8.0 и вам нужен TLS 1.3. Используйте TrustServerCertificate=yes только в средах разработки с самоподписанными сертификатами.

Keyword	Псевдонимы	По умолчанию	Описание
`Encrypt`	`encrypt`	`yes`	Включите шифрование TLS. Значения: `yes`, `no`, `strict`. Использование `strict`для TDS 8.0 с обязательным TLS 1.3.
`TrustServerCertificate`	`trust_server_certificate`, `trustservercertificate`	`no`	Доверяйте сертификатам сервера с авторегистрацией без проверки. Настроен `yes` только на разработку.
`HostnameInCertificate`	`hostnameincertificate`	Нет	Ожидаемое имя хоста в TLS-сертификате сервера.
`ServerCertificate`	`servercertificate`	Нет	Путь к PEM-файлу, содержащему доверенный сертификатный центр.
`ServerSPN`	`serverspn`	Нет	Server Service Principal Name for Kerberos authentication.

Высокая доступность и переключение при отказе

Эти ключевые слова охватывают группы доступности Always On, цели Azure SQL и устойчивость бездействующих соединений. Настройте ApplicationIntent=ReadOnly маршрутизацию рабочих нагрузок с большим количеством чтения (отчёты, аналитика) к вторичным репликам, что снижает нагрузку на основную копию. УстанавливайтеMultiSubnetFailover=yes, когда цель — База данных SQL Azure, Управляемый экземпляр SQL Azure, SQL база данных в Microsoft Fabric, слушатель группы доступности или экземпляр резервного кластера. Когда имя сервера разрешается на более чем один IP-адрес, драйвер подключается ко всем этим адресам одновременно и использует первый, который отвечает. Без него водитель пробует по адресам по одному. Адрес, который не отвечает, зависает до истечения тайм-аута TCP-подключения операционной системы, что может истечь время входа до того, как драйвер достигнет ответного адреса. Когда DNS разрешается по одному адресу, драйвер делает одну попытку подключения, поэтому параметр можно оставить включённым.

MultiSubnetFailover=yes имеет следующие ограничения. Нельзя использовать его через протокол, кроме TCP, подключение к инстансу SQL Server с более чем 64 IP-адресами не работает, и с зеркалированием базы данных нельзя. Зеркалирование базы данных устарело во всех поддерживаемых версиях SQL Server. Вместо этого используйте группы доступности AlwaysOn.

Keyword	Псевдонимы	По умолчанию	Описание
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Подключитесь ко всем разрешенным адресам одновременно и используйте первое успешное соединение.
`ApplicationIntent`	`applicationintent`	`ReadWrite`	Объявить тип нагрузки приложения. Используйте `ReadOnly` для маршрутизации только для чтения к вторичным репликам.
`ConnectRetryCount`	`connectretrycount`	`1`	Количество попыток автоматического переподключения для устойчивости соединения в режиме простоя. Это функция на уровне драйвера для обрыва холостых соединений, а не замена логике повторного тестирования на уровне приложения.
`ConnectRetryInterval`	`connectretryinterval`	`10`	Секунды между попытками восстановления устойчивости соединения в простое.

Выступления и сеть

Настройки по умолчанию работают для большинства приложений. Увеличение PacketSize (до 32767) для массовой передачи данных. Настройте KeepAlive , если соединения пересекают межсетевые экраны или балансировщики нагрузки, которые сбрасывают простоящие TCP-сессии.

Keyword	Псевдонимы	По умолчанию	Описание
`PacketSize`	`packet size`, `packetsize`	`4096`	Размер сетевого пакета в байтах (512–32767).
`KeepAlive`	`keepalive`	Нет	Интервал сохранения TCP за секунды.
`KeepAliveInterval`	`keepaliveinterval`	Нет	Интервал повторных попыток TCP keep-alive через секунды.
`IpAddressPreference`	`ipaddresspreference`	Нет	Предпочтение по семейству IP: `IPv4First`, `IPv6First`, `UsePlatformDefault`.

Зарезервированные ключевые слова

Keyword	Описание
`Driver`	Зарезервировано для внутреннего использования. Водитель автоматически управляет этим значением.
`APP`	Зарезервировано. Водитель всегда ставит на это `"MSSQL-Python"` .

Режимы аутентификации Microsoft Entra

Ключевое Authentication слово поддерживает следующие значения. Выберите режим, который соответствует вашему развертыванию:

Ценность	Описание	Когда использовать
`ActiveDirectoryDefault`	Использование `DefaultAzureCredential` из SDK Azure Identity. Пробует несколько методов аутентификации последовательно.	Local development across Azure CLI, Azure PowerShell and Azure Developer CLI. Для продакшена используйте определённый режим (`ActiveDirectoryMSI`, `ActiveDirectoryServicePrincipal`), чтобы избежать медленного перехода по цепочке учетных данных.
`ActiveDirectoryInteractive`	Интерактивный вход через браузер. В Windows делегирует напрямую драйвер ODBC.	Локальная разработка и инструменты, где пользователь присутствует для аутентификации в браузере.
`ActiveDirectoryDeviceCode`	Поток кода устройства для безголовых сред. Отображается код для ввода в `https://microsoft.com/devicelogin`.	SSH-сессии, контейнеры Docker или другие среды без браузера.
`ActiveDirectoryPassword`	Deprecated. Аутентификация по имени пользователя и паролю с помощью Microsoft Entra ID. Требуется `UID` и `PWD`. Использует поток ROPC, который несовместим с MFA.	Не рекомендуется. Вместо этого используются типы `ActiveDirectoryMSI` или `ActiveDirectoryServicePrincipal`.
`ActiveDirectoryMSI`	Управляемая идентификация сервиса для приложений, размещённых в Azure.	Azure VMs, App Service или Функции Azure, где управляемая идентичность конфигурирована. Учетные данные не требуются.
`ActiveDirectoryServicePrincipal`	Аутентификация принципа сервиса. Требуется `UID` (идентификатор клиента) и `PWD` (секрет клиента).	CI/CD конвейеры и фоновые сервисы, использующие зарегистрированный идентификатор приложения.
`ActiveDirectoryIntegrated`	Интегрированная аутентификация Windows с Microsoft Entra ID (Kerberos).	Машины Windows, объединённые с доменом, в корпоративных средах с настройкой Kerberos.

Для воспроизводимой настройки среды Docker, devcontainer и CI см. раздел Container and local development. В этой статье централизован выбор Python во время выполнения и показано, как использовать изображения, закреплённые по дайджесту, в общих средах.

Пример: DefaultAzureCredential

ActiveDirectoryDefaultотображается в цепочку Azure IdentityDefaultAzureCredential. Он сначала использует токен Azure CLI при локальной разработке, затем управляемый идентификатор при развертывании в Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Пример: поток кода устройства

Используйте поток кода устройства при работе в средах без браузера, таких как SSH-сессии или контейнеры Docker. Драйвер отображает URL и код для ввода на отдельном устройстве:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Пример: принципал сервиса

Аутентификация принципала сервиса использует зарегистрированную идентификацию приложения с клиентским идентификатором и секретом. Используйте этот подход для CI/CD конвейеров и фоновых сервисов, которые работают без участия пользователя:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Чтобы зарегистрировать приложение и предоставить ему доступ к базе данных, см. Microsoft Entra service principals с Azure SQL. Для полной настройки в mssql-python, см. Аутентификация главного сервиса.

Время соединения истекло

Установите тайм-аут аутентификации с параметром timeout . Используйте тайм-аут, чтобы приложение не зависало бесконечно, когда сервер недоступен:

# 30-second authentication timeout
conn = mssql_python.connect(connection_string, timeout=30)

Connection.timeout — это отдельная настройка, ограничивающая каждое утверждение, а не попытку аутентификации. Для получения дополнительной информации см . раздел «Тайм-аут соединения».

conn.timeout = 60

Если цель — База данных SQL Azure serverless с включенной автопаузой, используйте как минимум 60. Автоматически приостановленная база данных возобновляется при первой попытке подключения, и короткий тайм-аут истекает до завершения возобновления. Попытка также может провалиться из-за ошибки 40613 во время возобновления базы данных, поэтому приложение должно попробовать снова. Для получения дополнительной информации смотрите разделы «Автопауза и автовозобновление».

Режим автоматической фиксации

По умолчанию autocommit — False, что требует явных commit() вызовов. Включите автокоммит для DDL-операторов или запросов только для чтения, которые не требуют контроля транзакций:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Объекты учетных данных

Вместо того чтобы называть режим аутентификации в строка подключения, вы можете передать драйверу объект идентификации с этим token_provider параметром. Этот параметр принимает любой объект с определённым get_token(scope) методом, включая все учетные данные в azure-identity пакете:

import mssql_python
from azure.identity import DefaultAzureCredential

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Encrypt=yes",
    token_provider=DefaultAzureCredential(),
)

Не объединяйте token_provider с Authentication ключевым словом в одном соединении. Водитель поднимает InterfaceError , когда оба присутствуют. Дополнительные сведения см. в разделе проверки подлинности Microsoft Entra.

Атрибуты подключения

Задайте атрибуты соединения ODBC до установления соединения, используя attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Programmatic строка подключения building

Чтобы предотвратить инжекцию строка подключения, не используйте конкатенацию строк или f-strings с пользовательским входом. Используйте аргументы по ключевым словам или переменные среды. Для получения дополнительных шаблонов строительства, включая JSON/YAML конфигурационные файлы, Azure Key Vault и класс строителя, см. раздел «Программно построить строки соединений».

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Проверка строк соединения

Драйвер проверяет строки соединения и повышает ConnectionStringParseError значения для неизвестных или ошибочных ключевых слов:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Ключевые слова от других драйверов

Валидация выполняется до того, как драйвер откроет соединение, поэтому ключевое слово, которое принимают другие драйверы SQL Server, здесь сразу не работает. Строки соединения, портированные с ADO.NET, ODBC или pyodbc, обычно требуют следующих замен:

Ключевое слово в других драйверах	Эквивалент mssql-python
`Data Source`	`Server`, или его `addr` псевдонимов `address`
`Initial Catalog`	`Database`
`User ID`	`UID`
`Password`	`PWD`
`Connection Timeout`, `Connect Timeout`, `Timeout`, `Login Timeout`	Параметр `timeout` .`connect()` Для получения дополнительной информации см . раздел «Тайм-аут соединения».
`Application Name`	None. Драйвер устанавливает это значение и сообщает `Application Name` как неизвестное ключевое слово.
`APP`	None. Драйвер устанавливает это значение и сообщает `APP` как зарезервированное ключевое слово. Для получения дополнительной информации см. раздел «Зарезервированные ключевые слова».
`Pooling`, `Max Pool Size`	None. Настройте пул в коде. Для получения дополнительной информации см. раздел Пулирование соединений.
`Workstation ID`, `WSID`	None. Удалите ключевое слово из строка подключения.
`MultipleActiveResultSets`, `MARS_Connection`	None. Уберите ключевое слово. Для выполнения запросов одновременно используйте отдельные соединения. Для получения дополнительной информации см. раздел «Несколько курсоров».

Для APP и Driverдрайвер сообщает о ошибке по зарезервированному ключевому слову, а не о неизвестной ключевой ошибке, поскольку он контролирует оба значения.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-04