mssql-python için bağlantı dizileri

MSSQL-python sürücüsü, SQL Server, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Microsoft Fabric'te SQL database bağlanırken aşağıdaki bağlantı dizesi anahtar kelimelerini destekler.

Bağlantı dizisi söz dizimi

Bağlantı dizeleri, nokta virgülle ayrılmış anahtar-değer çiftleri kullanır:

keyword1=value1;keyword2=value2;...

Kıvırcık braketlerde özel karakterler (nokta virgül, eşitlik işaretleri veya kıvırcıl teller) içeren değerleri sarma:

PWD={my;complex=password}

Bir değere kelimesi kelimenin tam anlamıyla kapanış desteğini eklemek için iki kapanış desteği (}}):

PWD={password}}with}}brace}

Temel bağlantı örnekleri

Aşağıdaki örnekler, farklı kimlik doğrulama yöntemleriyle nasıl bağlanacağını göstermektedir. Üretim uygulamaları için mümkün olduğunda Microsoft Entra kimlik doğrulamasını kullanın. Şifreleri kod ve bağlantı dizilerinden kaldırır.

Bu örnekActiveDirectoryDefault, birden fazla kimlik kaynağı (Azure CLI, ortam değişkenleri, yönetilen kimlik) sırayla dener. Kodda şifre saklanmaz:

import mssql_python

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

SQL Server ile SQL doğrulama

SQL doğrulamasını yalnızca yerel geliştirme için kullan, kontrol ettiğiniz SQL Server örneğine karşı kullanın. Kimlik bilgileri bağlantı dizesi'e gömülüyor, bu yüzden onları kaynak kodda değil, ortam değişkenlerinde veya bir .env dosyada tutun:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL with Microsoft Entra authentication

Azure SQL Veritabanı için bağlantı dizesi, SQL Server ile aynıdır. ActiveDirectoryDefaultyerel geliştirme, konteynerler ve Azure barındırılan ortamlarda kod değişikliği olmadan çalışır:

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

Anahtar kelime argümanları kullanın

Bağlantı parametrelerini, bir bağlantı dizesi yerine veya ona ek olarak anahtar kelime argümanı olarak iletebilirsiniz. Anahtar kelime argümanları, bağlantı dizesi assembly'nin kaçış tuzaklarından kaçınır. Özel karakterlere sahip şifreler, , @;{, veya } anahtar kelime argümanı olarak geçirildiğinde kıvırcıl brace sarmalarına ihtiyaç duymaz:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Şifre içeren @ bir şifrenin wrap edilmesi gereken bağlantı dizesi assembly ile karşılaştırın:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Sürücü, normalizasyondan sonra anahtar kelime argümanlarını bağlantı dizesi'e birleştirir. Bir anahtar kelime argümanı zaten bağlantı dizesi'te bulunan bir parametreyle eşleşiyorsa, anahtar kelime argümanı öncelikli olur ve bağlantı dizesi değerini geçersiz kılar:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

Aşağıdaki örnek, bir bağlantı dizesi'i anahtar kelime argümanlarıyla birleştirir:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Bağlantı dizesi anahtar sözcükleri

Sunucu ve veritabanı

Bağlantı için hedef SQL Server örneği ve veritabanını belirtin.

Anahtar kelime Takma Adlar Varsayılan Açıklama
Server addr, address Hiçbiri SQL Server ana adı, IP adresi veya adlandırılmış örnek. Adlandırılmış server\instanceörnekler için . Azure SQL için server.database.windows.net. Bir port belirtmek için server,port.
Database Hiçbiri Hiçbiri Bağlanacak veritabanı adı.

Authentication

SQL kimlik doğrulaması için kimlik bilgileri sağlayın veya Microsoft Entra kimlik doğrulama modu belirtin. Şifresiz seçenekler için Microsoft Entra kimlik doğrulama modlarına bakınız.

Anahtar kelime Takma Adlar Varsayılan Açıklama
UID uid Hiçbiri SQL kimlik doğrulaması için kullanıcı adı.
PWD pwd Hiçbiri SQL kimlik doğrulaması için şifre.
Trusted_Connection trusted_connection no Windows Entegre kimlik doğrulamasını kullanın. Etkinleştirmek için yes olarak ayarlayın.
Authentication authentication Hiçbiri Microsoft Entra kimlik doğrulama modu. Bkz. Microsoft Entra kimlik doğrulaması.

Şifreleme ve güvenlik

Tüm bağlantılar varsayılan olarak kullanılır Encrypt=yes . Çoğu uygulama için varsayılan yeterlidir. Sadece SQL Server örneğin TDS 8.0'ı desteklediğinde ve TLS 1.3 gerektirdiğinde kullanınstrict. Yalnızca kendi kendine imzalanmış sertifikalarla geliştirme ortamlarında kullanılır TrustServerCertificate=yes .

Anahtar kelime Takma Adlar Varsayılan Açıklama
Encrypt encrypt yes TLS şifrelemesini etkinleştirin. Değerler: yes, no, strict. strict için zorunlu TLS 1.3 ile kullanım.
TrustServerCertificate trust_server_certificate, trustservercertificate no Doğrulama olmadan kendi kendine imzalanmış sunucu sertifikalarına güvenin. Sadece geliştirme için ayarlandı yes .
HostnameInCertificate hostnameincertificate Hiçbiri Sunucunun TLS sertifikasında beklenen host adı.
ServerCertificate servercertificate Hiçbiri Güvenilir sertifika otoritesini içeren bir PEM dosyasına giden yol.
ServerSPN serverspn Hiçbiri Kerberos doğrulaması için Sunucu Hizmet Adı.

Yüksek kullanılabilirlik ve hata durumunda yedek sisteme geçiş

Bu anahtar kelimeler Always On kullanılabilirlik gruplarını, Azure SQL hedeflerini ve boş bağlantı dayanıklılığını kapsar. Okuma ağırlıklı iş yüklerini (raporlar, analitikler) ikincil replikalara yönlendirmek için ayarlandı ApplicationIntent=ReadOnly , böylece birincil replikadaki yükü azalttı. Hedef Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'te SQL veritabanı, kullanılabilirlik grubu dinleyicisi veya failover kümesi örneği olduğunda ayarlanırMultiSubnetFailover=yes. Sunucu adı birden fazla IP adresi olarak çözüldüğünde, sürücü aynı anda tüm bu adreslere bağlanır ve ilk yanıt veren adresi kullanır. Onsuz sürücü adresleri teker teker dener. Cevap vermeyen bir adres, işletim sisteminin TCP bağlantı zaman aşımına kadar durur; bu da sürücünün cevap veren bir adrese ulaşmadan önce giriş süresini tüketebilir. DNS tek bir adrese çözüm bulduğunda, sürücü tek bir bağlantı girişimi yapar, böylece ayar açık bırakmak güvenli olur.

MultiSubnetFailover=yes aşağıdaki sınırları vardır. TCP dışında bir protokol üzerinden kullanamazsınız, 64'ten fazla IP adresiyle yapılandırılmış bir SQL Server örneğine bağlanmak başarısız olur ve veritabanı aynalama ile kullanamazsınız. Veritabanı aynalama, desteklenen tüm SQL Server sürümlerinde kullanımdan kaldırılmıştır. Bunun yerine Always On kullanılabilirlik gruplarını kullanın.

Anahtar kelime Takma Adlar Varsayılan Açıklama
MultiSubnetFailover multisubnetfailover no Tüm çözülen adreslere aynı anda bağlanın ve başarılı olan ilk bağlantıyı kullanın.
ApplicationIntent applicationintent ReadWrite Uygulama iş yükü türünü bildir. İkincil replikalara sadece okunabilir yönlendirme için kullanım ReadOnly .
ConnectRetryCount connectretrycount 1 Boşta bağlantı dayanıklılığı için otomatik yeniden bağlantı girişimlerinin sayısı. Bu, boşta bağlantıların kesilmesi için sürücü düzeyinde bir özelliktir, uygulama düzeyindeki yeniden deneme mantığının yerine geçmez.
ConnectRetryInterval connectretryinterval 10 Boşta bağlantı dayanıklılığı yeniden bağlantı denemeleri arasındaki saniyeler.

Performans ve ağ

Varsayılan ayarlar çoğu uygulama için çalışır. Toplu PacketSize veri transferleri için artış (32767'ye kadar). Bağlantıların güvenlik duvarlarını veya yük dengeleyicilerini aşarak boşta TCP oturumlarını düşürüp kesmediğini yapılandırın KeepAlive .

Anahtar kelime Takma Adlar Varsayılan Açıklama
PacketSize packet size, packetsize 4096 Ağ paket boyutu baytlarla (512–32767).
KeepAlive keepalive Hiçbiri TCP canlı kalma aralığı saniyelerde.
KeepAliveInterval keepaliveinterval Hiçbiri TCP tekrar deneme aralığını saniyeler içinde canlandırma süresi.
IpAddressPreference ipaddresspreference Hiçbiri IP adresi ailesi tercihi: IPv4First, IPv6First, UsePlatformDefault.

Ayrılmış anahtar sözcükler

Anahtar kelime Açıklama
Driver dahili kullanım için ayrılmıştır. Sürücü bu değeri otomatik olarak yönetir.
APP Rezerve edilmiş. Her zaman sürücü tarafından ayarlanır "MSSQL-Python" .

Microsoft Entra kimlik doğrulama modları

Anahtar kelime Authentication aşağıdaki değerleri destekler. Konuşlandırmanıza uygun modu seçin:

Değer Açıklama Ne zaman kullanılır?
ActiveDirectoryDefault Azure Identity SDK'dan kullanılan DefaultAzureCredential kullanımlar. Birden fazla kimlik doğrulama yöntemini ardışık olarak dener. Azure CLI, Azure PowerShell ve Azure Developer CLI genelinde yerel geliştirme. Üretim için, yavaş kimlik zinciri yürüyüşünü önlemek için özel bir mod (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) kullanın.
ActiveDirectoryInteractive Tarayıcı tabanlı etkileşimli giriş. Windows'ta, ODBC sürücüsüne doğal olarak delege edilir. Yerel geliştirme ve kullanıcının tarayıcıda kimlik doğrulama için bulunduğu araçlar.
ActiveDirectoryDeviceCode Başsız ortamlar için cihaz kodu akışı. Girilecek bir kod gösterir.https://microsoft.com/devicelogin SSH oturumları, Docker konteynerleri veya tarayıcı olmayan diğer ortamlar.
ActiveDirectoryPassword Deprecated. Microsoft Entra ID ile kullanıcı adı ve şifre doğrulaması. UID ve PWD gerektirir. MFA ile uyumlu olmayan ROPC akışını kullanır. Tavsiye edilmez. Bunun yerine ActiveDirectoryMSI veya ActiveDirectoryServicePrincipal kullanın.
ActiveDirectoryMSI Azure-hosted uygulamalar için Managed Service Identity. Azure VM'ler, App Service veya Azure İşlevleri, burada yönetilen kimlik konfigure edilir. Kimlik bilgileri gerekmez.
ActiveDirectoryServicePrincipal Hizmet ana doğrulaması. (İstemci kimliği) ve UID (istemci gizliliği) gerektirir PWD . Kayıtlı uygulama kimliği kullanan CI/CD boru hatları ve arka plan servisleri.
ActiveDirectoryIntegrated Windows Microsoft Entra ID (Kerberos) ile entegre kimlik doğrulama. Domain-joined Windows machines in enterprise environments with Kerberos configureed.

Tekrarlanabilir Docker, devcontainer ve CI ortam kurulumu için bkz. Konteyner ve yerel geliştirme. Bu makale, Python çalışma zamanı seçimini merkezileştirir ve paylaşılan ortamlarda digest-sabitlenmiş görüntülerin nasıl kullanılacağını gösterir.

Örnek: DefaultAzureCredential

ActiveDirectoryDefaultAzure Identity DefaultAzureCredential zincirine haritalanır. Yerel geliştirme sırasında önce Azure CLI token'ını dener, ardından Azure'a dağıtıldığında yönetilen kimliği dener:

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

Örnek: Cihaz kodu akışı

Tarayıcı olmayan ortamlarda, örneğin SSH oturumları veya Docker konteynerleri gibi ortamlarda çalışırken cihaz kod akışını kullanın. Sürücü, ayrı bir cihazda girilecek bir URL ve kod gösterir:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Örnek: Hizmet Başkanı

Hizmet ana doğrulaması, istemci kimliği ve gizli kayıtlı bir uygulama kimliği kullanır. Kullanıcı etkileşimi olmadan çalışan CI/CD boru hatları ve arka plan hizmetleri için bu yaklaşımı kullanın:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Uygulamayı kaydetmek ve veritabanına erişim vermek için Microsoft Entra servis prensipleri ile Azure SQL'e bakınız. Tam kurulum için mssql-pythonbkz. Hizmet ana doğrulaması.

Bağlantı zaman aşımına uğradı

Doğrulama zamanını parametreyle timeout ayarlayın. Sunucu ulaşılamadığında uygulamanızın süresiz olarak takılmasını önlemek için bir zaman aşımını kullanın:

# 30-second authentication timeout
conn = mssql_python.connect(connection_string, timeout=30)

Connection.timeout her ifadeyi tanım girişimi yerine sınırlayan ayrı bir ayardır. Daha fazla bilgi için Bağlantı Zaman Aşımı bölümüne bakınız.

conn.timeout = 60

Hedef otomatik duraklatma etkinliğinde Azure SQL Veritabanı sunucusuz ise, en azından 60. Otomatik duraklatılan veritabanı ilk bağlantı girişiminde devam eder ve daha kısa bir zaman aşımı devam tamamlanmadan önce geçer. Deneme veritabanı devam ederken 40613 hatasıyla da başarısız olabilir, bu yüzden uygulama tekrar denemek zorundadır. Daha fazla bilgi için bkz. Otomatik duraklatma ve otomatik devam.

Otomatik komut modu

Varsayılan olarak, autocommitFalse, açık commit() çağrılar gerektirir. İşlem kontrolü gerektirmeyen DDL ifadeleri veya yalnızca okunan sorgular için otomatik commit etkinleştirin:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Kimlik bilgisi nesneleri

Kimlik doğrulama modunu bağlantı dizesi'de adlandırmak yerine, sürücüye parametreyle token_provider birlikte bir credential nesnesi verebilirsiniz. Bu parametre, paketteki azure-identity tüm kimlik bilgilerini içeren herhangi bir get_token(scope) yöntemi olan nesneyi kabul eder:

import mssql_python
from azure.identity import DefaultAzureCredential

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Encrypt=yes",
    token_provider=DefaultAzureCredential(),
)

Aynı bağlantıdaki Authentication anahtar kelimeyle birleştirmeyintoken_provider. Sürücü, her ikisi de orada olduğunda havayı kaldırır InterfaceError . Daha fazla bilgi için bkz . Microsoft Entra kimlik doğrulaması.

Bağlantı öznitelikleri

Bağlantı kurulmadan önce ODBC bağlantı niteliklerini şu şekilde attrs_beforeayarlayın:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Programatik bağlantı dizesi oluşturma

bağlantı dizesi enjeksiyonunu önlemek için, kullanıcı girişiyle string concatation veya f-string kullanmayın. Bunun yerine anahtar kelime argümanları veya ortam değişkenleri kullanın. JSON/YAML yapılandırma dosyaları, Azure Key Vault ve bir builder sınıfı dahil olmak üzere daha fazla yapı desenleri için bkz. Bağlantı dizileri programatik olarak oluşturuluyor.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Bağlantı dizisi doğrulaması

Sürücü, bağlantı dizelerini doğrular ve bilinmeyen veya yanlış yazılmış anahtar kelimeler için yükseltme ConnectionStringParseError sağlar:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Diğer sürücülerden anahtar kelimeler

Doğrulama, sürücü bağlantı açmadan önce çalışır, bu yüzden diğer SQL Server sürücülerinin kabul ettiği anahtar kelime burada hemen başarısız olur. ADO.NET, ODBC veya pyodbc'den taşınan bağlantı dizeleri genellikle şu ikamelere ihtiyaç duyar:

Anahtar kelime diğer sürücülerde mssql-python karşılığı
Data Source Server, ya da onun addr ve address takma adların
Initial Catalog Database
User ID UID
Password PWD
Connection Timeout, Connect Timeout, Timeout, Login Timeout Parametreleritimeout.connect() Daha fazla bilgi için Bağlantı Zaman Aşımı bölümüne bakınız.
Application Name None. Sürücü bu değeri belirler ve bilinmeyen bir anahtar kelime olarak rapor verir Application Name .
APP None. Sürücü bu değeri ayarlar ve raporu ayrılmış anahtar kelime olarak bildirir APP . Daha fazla bilgi için Reserved anahtar kelimeleri sayfasına bakınız.
Pooling, Max Pool Size None. Kodda havuzlamayı yapılandırın. Daha fazla bilgi için Bağlantı havuzlaması bölümünü inceleyin.
Workstation ID, WSID None. Anahtar kelimeyi bağlantı dizesi'ten çıkarın.
MultipleActiveResultSets, MARS_Connection None. Anahtar kelimeyi kaldırın. Sorguları eşzamanlı çalıştırmak için ayrı bağlantılar kullanın. Daha fazla bilgi için bkz. Çoklu imleç.

ve DriveriçinAPP, sürücü bilinmeyen bir anahtar kelime hatası yerine rezerv edilmiş bir anahtar kelime hatası bildirir, çünkü her iki değeri de kontrol eder.

İlgili içerik

  • Last updated on