String koneksi untuk mssql-python

Driver mssql-python mendukung kata kunci string koneksi berikut saat menyambungkan ke SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric.

Sintaks string koneksi

String koneksi menggunakan pasangan nilai kunci yang dipisahkan titik koma:

keyword1=value1;keyword2=value2;...

Bungkus nilai yang berisi karakter khusus (titik koma, tanda sama dengan, atau kurung kurawal) dalam kurung kurawal:

PWD={my;complex=password}

Untuk menyertakan kurung kurawal penutup literal dalam nilai, gunakan dua kurung kurawal penutup (}}):

PWD={password}}with}}brace}

Contoh koneksi dasar

Contoh berikut menunjukkan cara menyambungkan menggunakan metode autentikasi yang berbeda. Untuk aplikasi produksi, gunakan autentikasi Microsoft Entra jika memungkinkan. Ini menghilangkan kata sandi dari kode dan string koneksi Anda.

Contoh ini menggunakan ActiveDirectoryDefault, yang mencoba beberapa sumber kredensial (Azure CLI, variabel lingkungan, identitas terkelola) secara berurutan. Tidak ada kata sandi yang disimpan dalam kode:

import mssql_python

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

SQL Server dengan autentikasi SQL

Gunakan autentikasi SQL hanya untuk pengembangan lokal terhadap instans SQL Server yang Anda kontrol. Kredensial disematkan dalam string koneksi, jadi simpan dalam variabel lingkungan atau .env file daripada dalam kode sumber:

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

Azure SQL dengan autentikasi Microsoft Entra

string koneksi untuk Azure SQL Database sama dengan SQL Server. ActiveDirectoryDefaultbekerja di lingkungan pengembangan lokal, container, dan Azure-hosted tanpa perubahan kode:

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

Gunakan argumen kata kunci

Anda dapat meneruskan parameter koneksi sebagai argumen kata kunci, bukan atau sebagai tambahan untuk string koneksi. Argumen kata kunci menghindari jebakan yang melarikan diri dari rakitan string koneksi. Sandi dengan karakter khusus seperti @, ;, , {atau } tidak memerlukan pembungkus kurung kurawal saat diteruskan sebagai argumen kata kunci:

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

Bandingkan dengan rakitan string koneksi, di mana kata sandi yang berisi @ harus dibungkus:

# 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")

Driver menggabungkan argumen kata kunci ke dalam string koneksi setelah normalisasi. Jika argumen kata kunci cocok dengan parameter yang sudah ada di string koneksi, argumen kata kunci diutamakan dan mengganti nilai string koneksi:

# 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"

Contoh berikut menggabungkan string koneksi dengan argumen kata kunci:

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

Kata kunci string koneksi

Server dan database

Tentukan instans SQL Server target dan database untuk koneksi.

Keyword Aliasi Default Deskripsi
Server addr, address None Nama host, alamat IP, atau instans bernama SQL Server. Untuk instans bernama, gunakan server\instance. Untuk Azure SQL, gunakan server.database.windows.net. Untuk menentukan port, gunakan server,port.
Database None None Nama database untuk disambungkan.

Authentication

Berikan kredensial untuk autentikasi SQL atau tentukan mode autentikasi Microsoft Entra. Untuk opsi tanpa kata sandi, lihat Mode autentikasi Microsoft Entra.

Keyword Aliasi Default Deskripsi
UID uid None Nama pengguna untuk autentikasi SQL.
PWD pwd None Kata sandi untuk autentikasi SQL.
Trusted_Connection trusted_connection no Gunakan autentikasi Terintegrasi Windows. Atur ke yes untuk mengaktifkan.
Authentication authentication None Mode otentikasi Microsoft Entra. Lihat autentikasi Microsoft Entra .

Enkripsi dan keamanan

Semua koneksi digunakan Encrypt=yes secara default. Untuk sebagian besar aplikasi, defaultnya sudah cukup. Gunakan strict hanya jika instans SQL Server Anda mendukung TDS 8.0 dan Anda memerlukan TLS 1.3. Gunakan TrustServerCertificate=yes hanya di lingkungan pengembangan dengan sertifikat yang ditandatangani sendiri.

Keyword Aliasi Default Deskripsi
Encrypt encrypt yes Aktifkan enkripsi TLS. Nilai: yes, no, strict. Gunakan strict untuk TDS 8.0 dengan TLS 1.3 wajib.
TrustServerCertificate trust_server_certificate, trustservercertificate no Memercayai sertifikat server yang ditandatangani sendiri tanpa validasi. Atur ke yes hanya untuk pengembangan.
HostnameInCertificate hostnameincertificate None Nama host yang diharapkan di sertifikat TLS server.
ServerCertificate servercertificate None Jalur ke file PEM yang berisi otoritas sertifikat tepercaya.
ServerSPN serverspn None Nama Server Service Principal untuk autentikasi Kerberos.

Ketersediaan tinggi dan pengalihan otomatis saat terjadi kegagalan

Kata kunci ini mencakup grup ketersediaan Always On, target Azure SQL, dan ketahanan koneksi idle. Atur ApplicationIntent=ReadOnly untuk merutekan beban kerja baca berat (laporan, analitik) ke replika sekunder, mengurangi beban pada primer. Tetapkan MultiSubnetFailover=yes kapan targetnya adalah Azure SQL Database, Azure SQL Managed Instance, database SQL di Microsoft Fabric, listener availability group, atau failover cluster instance. Ketika nama server diselesaikan ke lebih dari satu alamat IP, pengaturan ini memungkinkan upaya koneksi paralel dan driver menggunakan yang pertama berhasil. Menghilangkan kata kunci tidak menonaktifkannya dengan penyedia Rust. Perilaku Transparent Network IP Resolution (TNIR) penyedia Microsoft terpisah dari pengaturan ini. Untuk perbedaan provider, lihat Fitur yang didukung penyedia native.

MultiSubnetFailover=yes memiliki batasan sebagai berikut. Anda tidak dapat menggunakannya melalui protokol selain TCP, menghubungkan ke instance SQL Server yang dikonfigurasi dengan lebih dari 64 alamat IP gagal, dan Anda tidak dapat menggunakannya dengan pencerminan database. Pencerminan basis data sudah tidak digunakan lagi di semua versi SQL Server yang didukung. Gunakan grup ketersediaan AlwaysOn sebagai gantinya.

Keyword Aliasi Default Deskripsi
MultiSubnetFailover multisubnetfailover no dengan msodbcsql18; biasanya yes dengan mssql-odbc Hubungkan ke semua alamat yang telah diselesaikan secara bersamaan dan gunakan koneksi pertama yang berhasil. Untuk default dan opt-out penyedia Rust, lihat Default failover Multi-subnet.
ApplicationIntent applicationintent ReadWrite Deklarasikan jenis beban kerja aplikasi. Gunakan ReadOnly untuk perutean baca-saja ke replika sekunder.
ConnectRetryCount connectretrycount 1 Jumlah upaya penyambungan ulang otomatis untuk ketahanan koneksi siaga. Ini adalah fitur tingkat driver untuk koneksi idle yang terputus, bukan pengganti logika coba ulang tingkat aplikasi.
ConnectRetryInterval connectretryinterval 10 Detik antara upaya penyambungan ulang ketahanan koneksi siaga.

Performa dan jaringan

Default berfungsi untuk sebagian besar aplikasi. Peningkatan PacketSize (hingga 32767) untuk transfer data massal. Konfigurasikan KeepAlive jika koneksi melintasi firewall atau penyeimbang beban yang membatalkan sesi TCP yang menganggur.

Keyword Aliasi Default Deskripsi
PacketSize packet size, packetsize 4096 Ukuran paket jaringan dalam byte (512–32767).
KeepAlive keepalive None TCP keep-alive interval dalam hitungan detik.
KeepAliveInterval keepaliveinterval None Interval percobaan ulang tetap hidup TCP dalam hitungan detik.
IpAddressPreference ipaddresspreference None Preferensi keluarga alamat IP: IPv4First, IPv6First, . UsePlatformDefault

Nama aplikasi

Atur nama aplikasi agar Anda dapat membedakan beban kerja Anda dalam pemantauan sisi server.

Keyword Alias Default Deskripsi
APP Application Name MSSQL-Python Nama yang dilaporkan server untuk koneksi Anda.

Pengemudi menambah MSSQL-Python| nilai awal Anda. Misalnya, APP=orders-api melaporkan MSSQL-Python|orders-api ke server.

Anda juga dapat mengoper app="orders-api" ke connect(). Seperti kata kunci connection lainnya, argumen keyword menimpa nilai dalam string koneksi.

Nama muncul di dan APP_NAME()sys.dm_exec_sessions.program_name. Di Azure Synapse dedicated SQL pools, query sys.dm_pdw_exec_sessions.app_name instead. Untuk informasi lebih lanjut, lihat sys.dm_pdw_exec_sessions.

Koneksi sinkron, jalur async native eksperimental, dan salinan massal semuanya mengirim nama yang sama. Nama yang berbeda membuat pool koneksi terpisah, jadi gunakan satu nama untuk setiap beban kerja.

Nilai Anda tidak boleh kosong dan harus Unicode yang valid. Nama lengkap, termasuk MSSQL-Python|, dapat hingga 128 unit kode UTF-16, yang berarti 115 untuk nilai Anda. Beberapa karakter, seperti emoji, menggunakan dua unit kode. Nilai yang tidak valid akan menaikkan ValueError. Melewatkan nilai yang bukan string ke app argumen akan menimbulkan TypeError.

Kata kunci khusus

Keyword Deskripsi
Driver Dikhususkan untuk penggunaan internal. Driver mengelola nilai ini secara otomatis.

Mode otentikasi Microsoft Entra

Kata kunci mendukung Authentication nilai-nilai berikut. Pilih mode yang cocok dengan penyebaran Anda:

Nilai Deskripsi Kapan digunakan
ActiveDirectoryDefault Digunakan DefaultAzureCredential dari Azure Identity SDK. Mencoba beberapa metode autentikasi secara berurutan. Pengembangan lokal di seluruh Azure CLI, Azure PowerShell, dan Azure Developer CLI. Untuk produksi, gunakan mode tertentu (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) untuk menghindari perjalanan rantai kredensial yang lambat.
ActiveDirectoryInteractive Masuk interaktif berbasis browser. Di Windows, delegasikan ke driver ODBC secara asli. Pengembangan dan alat lokal di mana pengguna hadir untuk mengautentikasi di browser.
ActiveDirectoryDeviceCode Alur kode perangkat untuk lingkungan tanpa kepala. Menampilkan kode untuk dimasukkan di https://microsoft.com/devicelogin. Sesi SSH, kontainer Docker, atau lingkungan lain tanpa browser.
ActiveDirectoryPassword Deprecated. Autentikasi nama pengguna dan kata sandi dengan Microsoft Entra ID. Memerlukan UID dan PWD. Menggunakan alur ROPC, yang tidak kompatibel dengan MFA. Tidak disarankan. Gunakan ActiveDirectoryMSI atau ActiveDirectoryServicePrincipal sebagai gantinya.
ActiveDirectoryMSI Identitas Layanan Terkelola untuk aplikasi yang dihosting Azure. Azure VM, App Service, atau Azure Functions tempat identitas terkelola dikonfigurasi. Tidak diperlukan kredensial.
ActiveDirectoryServicePrincipal Autentikasi perwakilan layanan. Memerlukan UID (ID klien) dan PWD (rahasia klien). Alur CI/CD dan layanan latar belakang yang menggunakan identitas aplikasi terdaftar.
ActiveDirectoryIntegrated Autentikasi terintegrasi Windows dengan Microsoft Entra ID (Kerberos). Mesin Windows yang bergabung dengan domain di lingkungan perusahaan dengan Kerberos yang dikonfigurasi.

Untuk penyiapan lingkungan Docker, devcontainer, dan CI yang dapat direproduksi, lihat Kontainer dan pengembangan lokal. Artikel itu memusatkan pemilihan runtime Python dan menunjukkan cara menggunakan gambar yang disematkan intisari di lingkungan bersama.

Contoh: DefaultAzureCredential

ActiveDirectoryDefaultpeta ke rantai Azure IdentityDefaultAzureCredential. Ini mencoba token Azure CLI terlebih dahulu selama pengembangan lokal, lalu identitas terkelola saat disebarkan ke Azure:

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

Contoh: Alur kode perangkat

Gunakan alur kode perangkat saat berjalan di lingkungan tanpa browser, seperti sesi SSH atau kontainer Docker. Driver menampilkan URL dan kode untuk dimasukkan di perangkat terpisah:

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

Contoh: Perwakilan layanan

Autentikasi perwakilan layanan menggunakan identitas aplikasi terdaftar dengan ID klien dan rahasia. Gunakan pendekatan ini untuk alur CI/CD dan layanan latar belakang yang berjalan tanpa interaksi pengguna:

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

Untuk mendaftarkan aplikasi dan memberikannya akses database, lihat Perwakilan layanan Microsoft Entra dengan Azure SQL. Untuk penyiapan lengkap di mssql-python, lihat Autentikasi perwakilan layanan.

Waktu koneksi habis

Atur timeout autentikasi dengan parameter tersebut timeout . Gunakan batas waktu untuk mencegah aplikasi Anda hang tanpa batas waktu saat server tidak dapat dijangkau:

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

Connection.timeout adalah pengaturan terpisah yang membatasi setiap pernyataan, bukan upaya autentikasi. Untuk informasi lebih lanjut, lihat Timeout koneksi.

conn.timeout = 60

Jika targetnya adalah Azure SQL Database tanpa server dengan auto-pause diaktifkan, gunakan setidaknya 60. Database yang otomatis dijeda akan dilanjutkan pada upaya koneksi pertama, dan timeout yang lebih singkat akan berakhir sebelum resume selesai. Upaya juga dapat gagal dengan error 40613 saat database dilanjutkan, sehingga aplikasi harus mencoba ulang. Untuk informasi lebih lanjut, lihat Auto-pause dan auto-resume.

Mode penerapan otomatis

Secara default, autocommit adalah False, yang memerlukan panggilan eksplisit.commit() Aktifkan penerapan otomatis untuk pernyataan DDL atau kueri baca-saja yang tidak memerlukan kontrol transaksi:

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

# Or after connection
conn.setautocommit(True)

Objek kredensial

Alih-alih menamai mode autentikasi di string koneksi, Anda dapat memberikan objek kredensial dengan parameter tersebut token_provider kepada driver. Parameter ini menerima objek apa pun dengan metode get_token(scope) , termasuk setiap kredensial dalam azure-identity paket:

import mssql_python
from azure.identity import DefaultAzureCredential

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

Jangan gabungkan token_provider dengan Authentication kata kunci dalam koneksi yang sama. Driver menaikkan saat InterfaceError keduanya hadir. Untuk informasi selengkapnya, lihat Autentikasi Microsoft Entra.

Atribut koneksi

Atur atribut koneksi ODBC sebelum koneksi dibuat dengan menggunakan attrs_before:

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,
    }
)

Pembuatan string koneksi terprogram

Untuk mencegah injeksi string koneksi, jangan gunakan penggabungan string atau f-string dengan input pengguna. Gunakan argumen kata kunci atau variabel lingkungan sebagai gantinya. Untuk pola konstruksi lainnya termasuk file konfigurasi JSON/YAML, Azure Key Vault, dan kelas builder, lihat Membangun string koneksi secara terprogram.

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"
)

Validasi string koneksi

Driver memvalidasi string koneksi dan menaikkan ConnectionStringParseError untuk kata kunci yang tidak diketahui atau salah eja:

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

Kata kunci dari driver lain

Validasi berjalan sebelum driver membuka koneksi, sehingga kata kunci yang diterima driver SQL Server lain langsung gagal di sini. String koneksi yang dipindahkan dari ADO.NET, ODBC, atau pyodbc biasanya memerlukan substitusi berikut:

Kata kunci di driver lain padanan mssql-python
Data Source Server, atau alias dan miliknya addraddress
Initial Catalog Database
User ID UID
Password PWD
Connection Timeout, Connect Timeout, Timeout, Login Timeout Parameter timeout dari connect(). Untuk informasi lebih lanjut, lihat Timeout koneksi.
Application Name, APP Supported. Pengemudi menambahkan namanya sendiri di awal nilai Anda. Untuk informasi lebih lanjut, lihat Nama aplikasi.
Pooling, Max Pool Size None. Konfigurasikan pooling dalam kode. Untuk informasi selengkapnya, lihat Pengumpulan koneksi.
Workstation ID, WSID None. Hapus kata kunci dari string koneksi.
MultipleActiveResultSets, MARS_Connection None. Hapus kata kunci tersebut. Untuk menjalankan kueri secara bersamaan, gunakan koneksi terpisah. Untuk informasi lebih lanjut, lihat Multiple cursors.

Driver mengatur Driver dirinya sendiri, sehingga melaporkan kesalahan kata kunci yang dipesan untuk bukan Driver kesalahan kata kunci yang tidak diketahui.