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 seluruh pengembangan lokal, kontainer, dan lingkungan yang dihosting Azure 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 Prinsipal Layanan Server 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 diuraikan menjadi lebih dari satu alamat IP, driver terhubung ke semua alamat tersebut secara bersamaan dan menggunakan alamat pertama yang merespons. Tanpa itu, pengemudi mencoba alamat satu per satu. Alamat yang tidak menjawab akan terhenti sampai timeout TCP connect sistem operasi berakhir, yang dapat menghabiskan timeout login sebelum driver mencapai alamat yang menjawab. Ketika DNS mengarah ke satu alamat, driver hanya melakukan satu upaya koneksi, jadi pengaturan ini aman jika dibiarkan aktif.

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 Hubungkan ke semua alamat yang telah diselesaikan secara bersamaan dan gunakan koneksi pertama yang berhasil.
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

Kata kunci khusus

Keyword Deskripsi
Driver Dikhususkan untuk penggunaan internal. Driver mengelola nilai ini secara otomatis.
APP Direservasi. Selalu diatur oleh "MSSQL-Python" pengemudi.

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

ActiveDirectoryDefaultmemetakan ke rantai Identitas DefaultAzureCredential Azure. 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 daripada 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 address alias addr
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 None. Driver mengatur nilai ini dan melaporkan Application Name sebagai kata kunci yang tidak diketahui.
APP None. Driver mengatur nilai ini dan melaporkan APP sebagai kata kunci cadangan. Untuk informasi lebih lanjut, lihat Kata kunci yang dipesan.
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.

Untuk dan APPDriver, driver melaporkan kesalahan kata kunci yang dicadangkan daripada kesalahan kata kunci yang tidak diketahui, karena driver mengendalikan kedua nilai tersebut.

Konten terkait

  • Last updated on