Устранение проблем с установкой и подключением в mssql-python

Используйте эту статью для диагностики проблем с установкой, подключением, контейнером и непрерывной интеграцией (CI) драйвера mssql-python .

Проблемы с установкой

Установка pip завершается с ошибкой или выполняется сборка из исходного кода

Симптомы:

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

Возможные причины и решения:

  • Нет готового колеса для вашей платформы

  • Виртуальная среда не активирована

    • Сначала активируйте виртуальную среду. Установка в систему Python может привести к ошибкам или конфликтам разрешений.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Конфликтующие установки драйверов

Симптомы:

Вы сталкиваетесь с ошибками импорта или неожиданным поведением после установки mssql-python и pyodbc в той же среде.

Solution:

mssql-python и pyodbc могут сосуществовать. Если возникают конфликты, создайте чистую виртуальную среду.

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

Проблемы с подключением

Не удаётся подключиться к серверу

Симптомы:

OperationalError: [08001] (0) Client unable to establish connection

Возможные причины и решения:

  • Сервер недоступен

    • Проверьте, что имя сервера и порт правильны.
    • Проверьте сетевое подключение с помощью ping <server> или telnet <server> 1433.
    • Убедитесь, что межсетевой экран допускает исходящие соединения на порте 1433.

  • SQL Server не работает

    • Убедитесь, что сервис SQL Server запущен.
    • Для именованных экземпляров проверьте, работает ли сервис SQL Server Browser.

  • Azure SQL firewall rules

    • Добавьте IP-адрес клиента в правила межсетевого экрана Azure SQL в портале Azure.
    • Для Управляемый экземпляр SQL Azure убедитесь, что вы подключаетесь из разрешённой сети.

Проверьте базовую TCP-связь:

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

Сбой входа

Симптомы:

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

Возможные причины и решения:

  • Несоответствие режимов аутентификации

    • Для База данных SQL Azure, Управляемый экземпляр SQL Azure и базы данных SQL в Fabric предпочтительно использовать режим Microsoft Entra, например Authentication=ActiveDirectoryDefault.
    • Если вы целенаправленно используете SQL-аутентификацию, убедитесь, что сервер это разрешает и что вы используете правильный формат входа для этой конечной точки.

  • Неправильные учетные данные SQL-аутентификации

    • Проверьте идентификатор пользователя и пароль.
    • Для Azure SQL включите полный идентификатор пользователя: <user_id>@<server>.

  • User не существует в базе данных

    • Проверьте, что пользователь имеет доступ к указанной базе данных.
    • Проверьте, связан ли вход с пользователем базы данных.

  • Аутентификация не настроена

    • Используйте аутентификацию Microsoft Entra (рекомендую): Authentication=ActiveDirectoryDefault.
    • Если вы устраняете неполадки в локальном экземпляре SQL Server, который должен поддерживать проверку подлинности SQL Server, убедитесь, что используется смешанный режим проверки подлинности.

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

Симптомы:

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

Возможные причины и решения:

  • Сервер медленно отвечает

    • Увеличьте тайм-аут соединения.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Задержка сети

    • Проверьте сетевой путь к серверу.
    • Рассмотрим более короткий сетевой путь или виртуальную частную сеть (VPN).

  • Сервер под большой нагрузкой

    • Старайтесь подключаться в непиковые часы.
    • Свяжитесь с администратором вашей базы данных.

Ошибки SSL-сертификата

Симптомы:

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

Решения:

Предпочитайте проверенный сертификат или локальные паттерны разработки в контейнерной и локальной разработке. Используйте TrustServerCertificate=yes только для локальной разработки при работе с сервером, который вы контролируете.

Для разработки и тестирования с самоподписанным сертификатом:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Caution

TrustServerCertificate=yes — это резервный вариант, используемый только локально. Не используйте его в общих контейнерах разработки, конвейерах CI или рабочих развертываниях. Для получения дополнительной информации см. раздел Шифрование и сертификаты.

Для производства устанавливайте соответствующие сертификаты и используйте:

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

Вопросы контейнера и CI

Отсутствующие системные библиотеки в Linux

Симптомы:

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

Установите необходимые системные пакеты для вашего дистрибутива:

Distribution Команда установки
Ubuntu или Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat или Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Для примеров Dockerfile см. раздел Container and local development.

Ошибки macOS SSL после установки

Симптомы:

При подключении из macOS, особенно на Apple silicon, возникают ошибки, связанные с SSL.

Solution:

Установите OpenSSL с помощью Homebrew и установите флаги linker:

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Связанные материалы

  • Last updated on