mssql-pythonMicrosoft Server, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Microsoft Fabric'teki SQL veritabanı için Microsoft'un Python sürücüsüdür. Doğrudan Veritabanı Bağlantısı (DDBC) kullanıyor, böylece harici sürücü yöneticisi kurmadan bağlanabilirsiniz. Sürücü, Python 3.10 veya daha yeni sürümleri destekler ve Python Veritabanı API Spesifikasyonu 2.0 ile uyumludur; günlük geliştirme için Python dostu iyileştirmeler ekler.
Başlangıç noktanızı seçin
Azure SQL için üretim temeli
Bu örneği, üretim odaklı bir Azure SQL bağlantısı için bir başlangıç noktası olarak kullanın. Çevreden yapılandırmayı okur, yönetilen kimlik ile kimlik doğrulamasını sağlar ve Tablolu Veri Akışı (TDS) 8.0 şifrelemesini etkinleştirir. Ayrıca oturum açma ve her sorgu/komut için zaman aşımı sürelerini ayarlar, geçici hataları üstel bekleme ile yeniden dener (bağlantı hatalarında yeni bir bağlantı, kilitlenme gibi sorgu hatalarında ise aynı bağlantı kullanılarak), sonuçları günlüğe kaydeder ve kaynakların serbest bırakılması için bağlam yöneticilerini kullanır.
Bağlantı dizesindeki ConnectRetryCount ve ConnectRetryInterval anahtar sözcükleri, SQL Server boştaki bağlantı dayanıklılığını etkinleştirir: sürücü, kesilen boştaki bir bağlantıya şeffaf bir şekilde yeniden bağlanır. Bu, bu örnekte deadlock veya sorgu zaman aşımı gibi geçici bir hata nedeniyle başarısız olan bir sorguyu yeniden deneyen uygulama düzeyindeki yeniden denemeden farklıdır. İkisi tamamlayıcı, ikisini de sakla.
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()
Bu örnekteki her bir endişeyle ilgili daha derin rehberlik için Microsoft Entra kimlik doğrulama, Bağlantı havuzlama, Şifreleme ve sertifikalar, Yeniden deneme mantığı ve Hata işleme bölümlerine bakınız.
Temel özellikler
-
PEP 249 uyumluluğu: Standart
connect, cursor, execute, ve fetch* arayüzler, ayrıca Pythonic uzantılar.
-
Doğrudan Veritabanı Bağlantısı (DDBC): Harici sürücü yöneticisi gerekmez. Kur
mssql-python ve bağlanmaya hazırsınız.
-
Microsoft Entra ID kimlik doğrulaması: Yönetilen kimlikler ve hizmet sorumluları dahil olmak üzere kimlik doğrulama modları için yerleşik destek.
-
SQL Server ve Windows kimlik doğrulaması: Desteklenen platformlarda SQL oturum açma bilgileri, Kerberos ve Windows tek oturum açma (SSO).
-
Toplu kopyalama: Yerel TDS protokol desteğiyle büyük veri yükleri için yüksek performanslı toplu ekleme.
-
Yerel veri türü desteği: JSON, XML, uzamsal veriler, seyrek sütunlar, datetimeoffset ve ondalık/para türlerinin hassas biçimde işlenmesi.
-
Apache Arrow entegrasyonu: Pandas, Polars ve DuckDB ile hızlı veri alışverişi için sıfır kopya sonuç setleri .
-
Asenkron kalıplar: Sürücüyü
asyncio tabanlı uygulamalarla ve FastAPI ile ThreadPoolExecutor geçici çözümleriyle kullanın. Entegrasyon kalıpları için Async kalıplara bakınız.
-
Varsayılan olarak TLS: TLS şifreleme ve sertifika doğrulaması varsayılan olarak açık (ODBC Sürücü 18 aracılığıyla).
Encrypt=strict ayarlandığında TDS 8.0 şifrelemesi kullanılabilir.
Başlayın
Verilerle çalışma
| Makale |
Açıklama |
|
Sorguların yürütülmesi |
execute, executemany, çoklu ifadeli gruplar ve sonuç kümeleri. |
|
Veriler alınıyor |
fetchone, fetchmany, fetchall, ve akış desenleri. |
|
Parametreli sorgular |
SQL enjeksiyonunu önlemek için parametreleri güvenli şekilde bağlayın. |
|
Saklı prosedürler |
İşlemleri çağırın, çıktı parametrelerini okuyun ve sonuç kümelerini işleyin. |
|
İmleç yönetimi |
İmleç yaşam süreleri, kaydırma ve dizi boyutu ayarı. |
|
Satır nesneleri |
Satırlara indeks, isim veya eşleme olarak erişin. |
|
İşlem yönetimi |
Onaylama, geri alma, kaydetme noktaları ve yalıtım seviyeleri. |
|
Sayfalandırma |
Geniş sonuç kümeleri için anahtar tabanlı ve ofset tabanlı sayfalama kalıpları. |
|
Hata işleme |
mssql_python.Error, DatabaseError, ve SQL Server hata yapısı. |
|
Yeniden deneme mantığı |
Geçici hataları tespit edin ve üstel geri çekilme ile tekrar deneyin. |
SQL Server veri türleri ve özellikleri
| Makale |
Açıklama |
|
Veri türü eşlemeleri |
SQL Server-to-Python tipi tablo ve dönüştürme kuralları. |
|
Tarih saati yönetimi |
datetime, datetime2, datetimeoffset ve zaman dilimiyle ilgili hususlar. |
|
Ondalık ve para türleri |
Kesin sayısal tipler ve decimal.Decimal hassasiyet. |
|
Karakter dizisi ve Unicode verileri |
varchar, nvarchar, derlemeler ve kod sayfaları. |
|
NULL yönetimi |
Üç değerli mantık, nöbetçiler ve pandalar etkileşimli. |
|
İkili veri |
varbinary, image ve büyük nesnelerin akışını sağlama. |
|
Özel tip dönüştürücüler |
Özel türler için giriş ve çıkış dönüştürücülerini kaydedin. |
|
Toptan kopyalama işlemleri |
Toplu kopyalama API’si ile yüksek hacimli ekleme işlemleri. |
|
JSON verileri |
JSON'u FOR JSON ve OPENJSONile depolayın, sorgulayın ve parçalayın. |
|
XML veri |
xml veri türü, XPath ve XQuery ile çalışın. |
|
Uzamsal veriler |
Python'dan geometry ve geography türleri. |
|
Seyrek sütunlar |
Geniş tablolar için seyrek sütunlar ve sütun kümeleri. |
|
Şema bulma |
Veritabanlarını, tabloları, sütunları ve indeksleri inceleyin. |
Dağıtım ve işletim
mssql-python’a geçin
| Makale |
Açıklama |
|
pyodbc'den geçiş yapın |
pyodbc API'lerini ve bağlantı dizelerini mssql-python'a eşleyin. |
|
pymssql'den geçiş |
Davranışı koruyarak pymssql'i mssql-python ile değiştirin. |
|
SQLite'den Migrate |
Yerel SQLite iş yüklerini SQL Server veya Azure SQL'e taşıyın. |
|
PostgreSQL'den geçiş |
PostgreSQL'den SQL Server'a mssql-python ile geçiş yapan Python geliştiricileri için tek durak rehber. |
Referans
| Makale |
Açıklama |
|
Destek yaşam döngüsü |
Desteklenen Python ve SQL Server sürümleri ve güncelleme sıklığı. |
|
Yenilikler |
Sürüm geçmişi ve sürüm notlarındaki öne çıkanlar. |
İlgili içerik