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.

Microsoft Entra doğrulama ile SQL Server (önerilir)

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`. TDS 8.0 için zorunlu TLS 1.3 ile kullanım`strict`.
`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 erişilebilirlik grubu dağıtımları için geçerlidir. 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ı. Erişilebilirlik grubunuzun birden fazla alt ağı aştığında ayarlan MultiSubnetFailover=yes .

Anahtar kelime	Takma Adlar	Varsayılan	Açıklama
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Always Açık erişilebilirlik grupları için çoklu alt ağ failover'ı etkinleştirin.
`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 `PWD` (istemci gizliliği) gerektirir `UID` .	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ı

Bağlantı zaman aşımını parametreyi timeout kullanarak 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 connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Mevcut bir bağlantının zaman aşımını da değiştirebilirsiniz:

conn.timeout = 60

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)

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'

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-22