Строки соединения для 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 Availability Group. Настройте ApplicationIntent=ReadOnly маршрутизацию рабочих нагрузок с большим количеством чтения (отчёты, аналитика) к вторичным репликам, что снижает нагрузку на основную копию. Установите MultiSubnetFailover=yes , когда ваша группа доступности охватывает несколько подсетей.

Keyword	Псевдонимы	По умолчанию	Описание
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Включите много-подсетевое резервное переключение для групп доступности Always On.
`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 connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Вы также можете изменить тайм-аут существующего соединения:

conn.timeout = 60

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

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

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

# Or after connection
conn.setautocommit(True)

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

Задайте атрибуты соединения 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'

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

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

Last updated on 2026-07-22