Řešení problémů s instalací a připojením pomocí mssql-python

Použijte tento článek k diagnostice problémů s instalací, připojením, kontejnerem a kontinuální integrací (CI) s ovladačem mssql-python .

Problémy s instalací

Instalace PIP selže nebo se sestaví ze zdrojového kódu

Příznaky:

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

Možné příčiny a řešení:

  • Pro vaši platformu není k dispozici žádný předem sestavený balíček wheel

    • Zkontrolujte, že používáte podporovanou verzi Python (verze 3.10 a vyšší) a platformu. Viz Životní cyklus podpory, kde najdete matici kompatibility.
    • Aktualizujte pip před instalací pomocí pip install --upgrade pip.
    • Pro opakovatelná prostředí pro týmy použijte uzamčený workflow v Opakovatelných nasazeních nebo kontejnerové postupy v Kontejnerech a místním vývoji, abyste omezili odchylky v konfiguraci místních počítačů.

  • Virtuální prostředí neaktivováno

    • Nejprve aktivujte své virtuální prostředí. Instalace do systémového Python může způsobit chyby oprávnění nebo konflikty.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Konfliktní instalace ovladačů

Příznaky:

Po instalaci mssql-python a pyodbc ve stejném prostředí se setkáte s chybami při importu nebo neočekávaným chováním.

Solution:

mssql-python a pyodbc mohou koexistovat. Pokud narazíte na konflikty, vytvořte čisté virtuální prostředí.

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

Problémy s připojením

Nelze se připojit k serveru

Příznaky:

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

Možné příčiny a řešení:

  • Server není dostupný

    • Ověřte, že název serveru a port jsou správné.
    • Zkontrolujte síťové připojení pomocí ping <server> nebo telnet <server> 1433.
    • Ujistěte se, že firewall umožňuje odchozí připojení na portu 1433.

  • SQL Server neběží

    • Ověřte, že služba SQL Server byla spuštěna.
    • Pro pojmenované instance ověřte, že služba SQL Server Browser běží.

  • Azure SQL firewall rules

    • Přidejte IP adresu svého klienta do pravidel Azure SQL firewallu v portálu Azure.
    • Pro Azure SQL Managed Instance se ujistěte, že se připojíte z povolené sítě.

Otestujte základní TCP konektivitu:

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}")

Přihlášení se nezdařilo.

Příznaky:

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

Možné příčiny a řešení:

  • Nesoulad autentizačního režimu

    • Pro Azure SQL Database, Azure SQL Managed Instance a SQL database in Fabric preferují režim Microsoft Entra, například Authentication=ActiveDirectoryDefault.
    • Pokud používáte SQL autentizaci záměrně, ověřte, že server to umožňuje a že používáte správný přihlašovací formát pro daný endpoint.

  • Nesprávné SQL autentizační údaje

    • Ověřte uživatelské ID a heslo.
    • Pro Azure SQL zahrňte plné uživatelské ID: <user_id>@<server>.

  • Uživatel v databázi neexistuje

    • Ověřte, že uživatel má přístup ke specifikované databázi.
    • Zkontrolujte, zda je přihlášení přiřazeno uživateli databáze.

  • Autentizace není nakonfigurována

    • Používejte Microsoft Entra autentizaci (doporučeno): Authentication=ActiveDirectoryDefault.
    • Pokud řešíte problém s lokální instancí SQL Server, která by měla přijímat SQL autentizaci, ověřte, že SQL Server používá autentizaci v kombinovaném režimu.

Časový limit připojení vypršel

Příznaky:

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

Možné příčiny a řešení:

  • Server reaguje pomalu

    • Zvyšte časový limit připojení.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latence sítě

    • Zkontrolujte síťovou cestu k serveru.
    • Zvažte kratší síťovou cestu nebo virtuální privátní síť (VPN).

  • Server pod velkým zatížením

    • Snažte se připojit mimo špičku.
    • Kontaktujte správce své databáze.

Chyby certifikátu SSL

Příznaky:

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

Řešení:

Preferujte důvěryhodný certifikát nebo místní vývojové vzorce v kontejnerech a lokálním rozvoji. Používejte TrustServerCertificate=yes pouze pro lokální vývoj na serveru, který ovládáte.

Pro vývoj a testování s vlastním podpisem certifikátu:

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 je to záložní varianta pouze pro místní obyvatele. Nepřenášejte to do sdílených vývojových kontejnerů, CI pipeline nebo produkčních nasazení. Pro více informací viz Šifrování a certifikáty.

Pro produkci nainstalujte příslušné certifikáty a použijte:

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

Problémy s kontejnery a CI

Chybějící systémové knihovny na Linuxu

Příznaky:

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

Solution:

Nainstalujte potřebné systémové balíčky pro vaši distribuci:

Distribution Instalační příkaz
Ubuntu nebo Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat nebo Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Pro příklady Dockerfile viz Container a lokální vývoj.

Chyby macOS SSL po instalaci

Příznaky:

Při připojení z macOS se setkáváte s chybami souvisejícími se SSL, zejména na Apple Silicon.

Solution:

Nainstalujte OpenSSL pomocí Homebrew a nastavte příznaky pro linker:

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

Související obsah

  • Last updated on