mssql-pythonadalah driver Python Microsoft untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric. Ini menggunakan Direct Database Connectivity (DDBC), sehingga Anda dapat terhubung tanpa menginstal pengelola driver eksternal. Driver mendukung Python 3.10 atau yang lebih baru dan mematuhi Spesifikasi API Database Python 2.0 sambil menambahkan peningkatan ramah Python untuk pengembangan sehari-hari.
Pilih titik awal Anda
Garis besar produksi untuk Azure SQL
Gunakan sampel ini sebagai titik awal untuk koneksi Azure SQL berorientasi produksi. Ini membaca konfigurasi dari lingkungan, mengautentikasi dengan identitas terkelola, dan mengaktifkan enkripsi Tabular Data Stream (TDS) 8.0. Ini juga mengatur batas waktu login dan batas waktu kueri untuk setiap pernyataan, mencoba kembali saat terjadi kegagalan sementara dengan backoff eksponensial (koneksi baru untuk kesalahan koneksi, koneksi yang sama untuk kesalahan kueri seperti deadlock), mencatat hasilnya, dan mengandalkan manajer konteks untuk melepaskan sumber daya.
Kata kunci ConnectRetryCount dan ConnectRetryInterval dalam string koneksi mengaktifkan ketahanan koneksi idle SQL Server: driver akan secara transparan menyambungkan ulang koneksi idle yang terputus. Itu berbeda dengan percobaan ulang pada tingkat aplikasi dalam sampel ini, yang mencoba kembali menjalankan kueri yang gagal karena kesalahan sementara seperti kebuntuan atau waktu tunggu kueri habis. Keduanya saling melengkapi, jadi pertahankan keduanya.
import logging
import os
import time
import mssql_python
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
logger = logging.getLogger("app")
# Transient errors that require a fresh connection to recover.
CONNECT_RETRY_ERRORS = frozenset({
"Timeout expired",
"Connection timeout expired",
"Client unable to establish connection",
"Communication link failure",
"Connection failure during transaction",
})
# Transient errors that leave the connection usable, such as a deadlock victim
# or a query timeout, so retry on the same connection.
QUERY_RETRY_ERRORS = frozenset({
"Serialization failure",
"Timeout expired",
})
def connect_with_retry(conn_str: str, max_attempts: int = 3, login_timeout_s: int = 5) -> mssql_python.Connection:
"""Open a connection, retrying transient failures with exponential backoff."""
for attempt in range(1, max_attempts + 1):
try:
conn = mssql_python.connect(
conn_str,
attrs_before={mssql_python.SQL_ATTR_LOGIN_TIMEOUT: login_timeout_s},
)
logger.info("connected on attempt %d/%d", attempt, max_attempts)
return conn
except mssql_python.OperationalError as exc:
if exc.driver_error not in CONNECT_RETRY_ERRORS or attempt == max_attempts:
logger.error("connect failed on attempt %d/%d: %s", attempt, max_attempts, exc.driver_error)
raise
delay = 2 ** (attempt - 1) # 1s, 2s, 4s
logger.warning(
"connect attempt %d/%d hit transient error %r; retrying in %ds",
attempt, max_attempts, exc.driver_error, delay,
)
time.sleep(delay)
def execute_with_retry(
conn: mssql_python.Connection,
sql: str,
*params,
max_attempts: int = 3,
query_timeout_s: int = 10,
) -> mssql_python.Cursor:
"""Run sql on an open connection and return the ready-to-fetch cursor.
Retries errors that leave the connection usable so callers don't wrap each
query in its own function. Pass query values as parameters. Retry only
idempotent statements; wrap writes in an explicit transaction.
"""
for attempt in range(1, max_attempts + 1):
cursor = mssql_python.Cursor(conn, timeout=query_timeout_s)
try:
cursor.execute(sql, *params)
if attempt > 1:
logger.info("query succeeded on attempt %d/%d", attempt, max_attempts)
return cursor
except mssql_python.OperationalError as exc:
cursor.close()
if exc.driver_error not in QUERY_RETRY_ERRORS or attempt == max_attempts:
logger.error("query failed on attempt %d/%d: %s", attempt, max_attempts, exc.driver_error)
raise
delay = 2 ** (attempt - 1) # 1s, 2s, 4s
logger.warning(
"query attempt %d/%d hit transient error %r; retrying in %ds",
attempt, max_attempts, exc.driver_error, delay,
)
time.sleep(delay)
raise RuntimeError("unreachable: the retry loop exits by return or raise")
def main() -> None:
# Read configuration from the environment; never hard-code secrets.
server = os.environ["SQL_SERVER"] # for example, myserver.database.windows.net
database = os.environ["SQL_DATABASE"] # for example, AdventureWorks
client_id = os.getenv("AZURE_CLIENT_ID") # set for a user-assigned managed identity
# Authenticate with the workload's managed identity over TDS 8.0 encryption.
# ConnectRetryCount/ConnectRetryInterval transparently reconnect a dropped
# idle connection; they don't replay a failed query.
conn_str = (
f"Server={server};"
f"Database={database};"
"Authentication=ActiveDirectoryMsi;"
"Encrypt=strict;"
"ConnectRetryCount=3;"
"ConnectRetryInterval=10;"
)
if client_id:
conn_str += f"UID={client_id};"
query = """
SELECT TOP 10
p.BusinessEntityID,
p.FirstName,
p.LastName
FROM Person.Person AS p
ORDER BY p.BusinessEntityID;
"""
try:
# Context managers close the cursor and connection automatically.
with connect_with_retry(conn_str) as conn:
with execute_with_retry(conn, query) as cursor:
for business_entity_id, first_name, last_name in cursor.fetchall():
print(f"{business_entity_id}\t{first_name}\t{last_name}")
except mssql_python.Error:
logger.exception("query failed")
raise
if __name__ == "__main__":
main()
Untuk panduan yang lebih mendalam tentang setiap masalah dalam sampel ini, lihat autentikasi Microsoft Entra, Pengumpulan koneksi, Enkripsi dan sertifikat, Logika coba lagi, dan Penanganan kesalahan.
Fitur utama
-
Kepatuhan PEP 249: Standar
connect, cursor, , executedan fetch* antarmuka, ditambah ekstensi Pythonic.
-
Konektivitas Database Langsung (DDBC): Tidak diperlukan pengelola driver eksternal. Instal
mssql-python dan Anda siap untuk terhubung.
-
Autentikasi Microsoft Entra ID: Dukungan bawaan untuk mode autentikasi, termasuk identitas terkelola dan perwakilan layanan.
-
SQL Server dan autentikasi Windows: login SQL, Kerberos, dan sekali masuk (SSO) Windows pada platform yang didukung.
-
Salinan massal: Sisipan massal berperforma tinggi untuk pemuatan data besar dengan dukungan protokol TDS asli.
-
Dukungan tipe data asli: JSON, XML, spasial, kolom jarang, datetimeoffset, dan desimal/uang dengan penanganan yang tepat.
-
Integrasi Apache Arrow: Set hasil tanpa penyalinan untuk pertukaran data cepat dengan pandas, Polars, dan DuckDB.
-
Pola asinkron: Gunakan driver dengan aplikasi berbasis
asyncio dan FastAPI melalui solusi alternatif ThreadPoolExecutor. Lihat Pola Asinkron untuk pola integrasi.
-
TLS secara default: Enkripsi TLS dan validasi sertifikat aktif secara default (melalui Driver ODBC 18). Enkripsi TDS 8.0 tersedia saat Anda mengatur
Encrypt=strict.
Mulai sekarang!
| Artikel |
Deskripsi |
|
String koneksi |
Sintaks string koneksi, kata kunci umum, dan contoh. |
|
Membangun string koneksi secara terprogram |
Buat string koneksi dengan aman dari konfigurasi dan rahasia. |
|
Manajemen koneksi |
Buka, gunakan kembali, dan tutup koneksi dengan bersih. |
|
Pengumpulan koneksi |
Penyetelan kolam, masa pakai, dan pola penggunaan kembali. |
|
Enkripsi dan sertifikat |
Mode enkripsi TLS, validasi sertifikat, dan TDS 8.0. |
|
Autentikasi Microsoft Entra |
Autentikasi tanpa kata sandi untuk Azure SQL dengan identitas terkelola, prinsipal layanan, alur interaktif, dan alur kode perangkat. |
|
Praktik terbaik keamanan |
Parameterisasi, manajemen rahasia, hak istimewa terkecil, dan enkripsi. |
|
Grup ketersediaan |
Hubungkan ke grup ketersediaan Always On dan replika baca-saja. |
Bekerja dengan data
| Artikel |
Deskripsi |
|
Menjalankan kueri |
execute, executemany, batch beberapa pernyataan, dan himpunan hasil. |
|
Mengambil data |
fetchone, fetchmany, fetchall, dan pola streaming. |
|
Kueri berparameter |
Mengikat parameter dengan aman untuk mencegah injeksi SQL. |
|
Prosedur tersimpan |
Panggil prosedur, baca parameter keluaran, dan proses kumpulan hasil. |
|
Manajemen kursor |
Masa pakai kursor, pengguliran, dan penyetelan ukuran array. |
|
Objek baris |
Akses baris berdasarkan indeks, nama, atau sebagai pemetaan. |
|
Manajemen transaksi |
Commit, rollback, titik simpan, dan tingkat isolasi. |
|
Paginasi |
Pola paginasi keyset dan offset pada kumpulan hasil berukuran besar. |
|
Penanganan kesalahan |
mssql_python.Error, DatabaseError, dan struktur kesalahan SQL Server. |
|
Logika coba lagi |
Deteksi kesalahan sementara dan coba lagi dengan jeda mundur eksponensial. |
Jenis dan fitur data SQL Server
| Artikel |
Deskripsi |
|
Pemetaan jenis data |
Tabel tipe SQL Server-ke-Python dan aturan konversi. |
|
Penanganan tanggal dan waktu |
datetime, datetime2, , datetimeoffsetdan pertimbangan zona waktu. |
|
Tipe desimal dan tipe mata uang |
Tipe numerik eksak dan decimal.Decimal presisi. |
|
Data string dan Unicode |
varchar, nvarchar, kolasi, dan halaman kode. |
|
Penanganan NULL |
Logika tiga nilai, penjaga, dan panda interop. |
|
Data biner |
varbinary, image, dan streaming objek besar. |
|
Konverter tipe khusus |
Daftarkan konverter input dan output untuk jenis kustom. |
|
Operasi penyalinan massal |
Penyisipan berthroughput tinggi dengan API penyalinan massal. |
|
Data JSON |
Simpan, kueri, dan cabik-cabik JSON dengan FOR JSON dan OPENJSON. |
|
Data XML |
Bekerja dengan tipe xml data, XPath, dan XQuery. |
|
Data spasial |
geometry dan geography tipe dari Python. |
|
Kolom jarang terisi |
Kolom dan kumpulan kolom jarang untuk tabel lebar. |
|
Penemuan skema |
Periksa database, tabel, kolom, dan indeks. |
Terapkan dan operasikan
Bermigrasi ke mssql-python
Reference
Konten terkait