Memecahkan masalah instalasi dan koneksi dengan mssql-python

Gunakan artikel ini untuk mendiagnosis masalah instalasi, koneksi, kontainer, dan integrasi kontinu (CI) dengan mssql-python driver.

Masalah penginstalan

pip gagal diinstal atau dikompilasi dari kode sumber

Gejala:

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

Kemungkinan penyebab dan solusi:

  • Tidak ada roda bawaan untuk platform Anda

    • Periksa bahwa Anda menjalankan versi Python yang didukung (versi 3.10 dan versi lebih baru) dan platformnya. Lihat Siklus hidup dukungan untuk matriks kompatibilitas.
    • Perbarui pip sebelum instalasi dengan pip install --upgrade pip.
    • Untuk lingkungan tim yang dapat diulang, gunakan alur kerja terkunci di Penyebaran yang dapat diulang atau pola kontainer di Kontainer dan pengembangan lokal untuk mengurangi penyimpangan mesin lokal.

  • Lingkungan virtual tidak diaktifkan

    • Aktifkan lingkungan virtual Anda terlebih dahulu. Instalasi ke dalam sistem Python dapat menyebabkan kesalahan izin atau konflik.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • Pustaka sistem Linux yang hilang

Penginstalan driver yang bertentangan

Gejala:

Anda mengalami kesalahan impor atau perilaku tak terduga setelah menginstal mssql-python dan pyodbc dalam lingkungan yang sama.

Solution:

mssql-python dan pyodbc dapat hidup berdampingan. Jika Anda mengalami konflik, buatlah lingkungan virtual yang bersih.

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

Masalah koneksi

Tidak dapat terhubung ke server

Gejala:

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

Kemungkinan penyebab dan solusi:

  • Server tidak dapat dijangkau

    • Pastikan nama server dan port sudah benar.
    • Periksa konektivitas jaringan dengan ping <server> atau telnet <server> 1433.
    • Pastikan firewall memungkinkan koneksi keluar pada port 1433.

  • SQL Server tidak berjalan

    • Pastikan layanan SQL Server sudah dijalankan.
    • Untuk instance bernama, pastikan layanan Browser SQL Server berjalan.

  • Aturan firewall Azure SQL

    • Tambahkan alamat IP klien Anda ke aturan firewall Azure SQL di portal Azure.
    • Untuk Azure SQL Managed Instance, pastikan Anda terhubung dari jaringan yang diizinkan.

Uji konektivitas dasar 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}")

Gagal masuk

Gejala:

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

Kemungkinan penyebab dan solusi:

  • Ketidakcocokan mode autentikasi

    • Untuk Azure SQL Database, Azure SQL Managed Instance, dan database SQL dalam Fabric, sebaiknya gunakan mode autentikasi Microsoft Entra seperti Authentication=ActiveDirectoryDefault.
    • Jika Anda sengaja menggunakan autentikasi SQL, pastikan server mengizinkannya dan Anda menggunakan format login yang benar untuk endpoint tersebut.

  • Kredensial autentikasi SQL yang salah

    • Verifikasi ID pengguna dan kata sandi.
    • Untuk Azure SQL, sertakan ID pengguna lengkap: <user_id>@<server>.

  • Pengguna tidak ada di database

    • Verifikasi bahwa pengguna memiliki akses ke database yang ditentukan.
    • Periksa apakah proses masuk dipetakan ke pengguna basis data.

  • Autentikasi tidak dikonfigurasi

    • Gunakan autentikasi Microsoft Entra (disarankan): Authentication=ActiveDirectoryDefault.
    • Jika Anda memecahkan masalah instance SQL Server lokal yang seharusnya menerima autentikasi SQL, pastikan SQL Server menggunakan autentikasi mode campuran.

Waktu koneksi habis

Gejala:

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

Kemungkinan penyebab dan solusi:

  • Server lambat merespons

    • Tingkatkan batas waktu koneksi.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latensi jaringan

    • Periksa jalur jaringan ke server.
    • Pertimbangkan jalur jaringan yang lebih pendek atau virtual private network (VPN).

  • Server di bawah beban berat

    • Cobalah untuk terhubung di jam sepi.
    • Hubungi administrator database Anda.

Kesalahan sertifikat SSL

Gejala:

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

Solusi:

Sebaiknya gunakan sertifikat tepercaya atau pola pengembangan lokal di Container dan pengembangan lokal. Gunakan TrustServerCertificate=yes hanya untuk pengembangan lokal terhadap server yang Anda kendalikan.

Untuk pengembangan dan pengujian dengan sertifikat yang ditandatangani sendiri:

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 adalah cadangan yang hanya bersifat lokal. Jangan bawa ke kontainer pengembangan bersama, pipeline CI, atau deployment produksi. Untuk informasi selengkapnya, lihat Enkripsi dan sertifikat.

Untuk produksi, pasang sertifikat yang sesuai dan gunakan:

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

Masalah kontainer dan CI

Pustaka sistem yang hilang di Linux

Gejala:

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

Solution:

Instal paket sistem yang diperlukan untuk distribusi Anda:

Distribution Perintah instalasi
Ubuntu atau Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat atau Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Untuk contoh Dockerfile, lihat Kontainer dan pengembangan lokal.

Kesalahan SSL macOS setelah penginstalan

Gejala:

Anda akan mengalami kesalahan terkait SSL saat terhubung dari macOS, terutama di Apple Silicon.

Solution:

Instal OpenSSL dengan Homebrew, dan atur flag linker:

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

Konten terkait

  • Last updated on