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.

SQL Server dengan autentikasi Microsoft Entra (disarankan)

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 berlaku untuk penyebaran grup ketersediaan Always On. Atur ApplicationIntent=ReadOnly untuk merutekan beban kerja baca berat (laporan, analitik) ke replika sekunder, mengurangi beban pada primer. Atur MultiSubnetFailover=yes kapan grup ketersediaan Anda menjangkau beberapa subnet.

Keyword	Aliasi	Default	Deskripsi
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Aktifkan failover multi-subnet untuk grup ketersediaan Always On.
`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 batas waktu koneksi menggunakan timeout parameter. Gunakan batas waktu untuk mencegah aplikasi Anda hang tanpa batas waktu saat server tidak dapat dijangkau:

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

Anda juga dapat mengubah batas waktu pada koneksi yang ada:

conn.timeout = 60

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)

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'

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-22