DSN dan Kata Kunci dan Atribut String Sambungan
Halaman ini mencantumkan kata kunci untuk string koneksi dan DSN, dan atribut koneksi untuk SQLSetConnectAttr dan SQLGetConnectAttr, tersedia di Driver ODBC untuk SQL Server.
Kata Kunci String DSN/Koneksi yang Didukung dan Atribut Koneksi
Tabel berikut mencantumkan kata kunci yang tersedia dan atribut untuk setiap platform (L: Linux; M: macOS; W: Windows). Pilih kata kunci atau atribut untuk detail selengkapnya.
Berikut adalah beberapa string koneksi kata kunci dan atribut koneksi, yang tidak didokumenkan dalam Menggunakan Kata Kunci String Koneksi dengan SQL Server Native Client, SQLSetConnectAttr, dan Fungsi SQLSetConnectAttr.
Deskripsi
Digunakan untuk menjelaskan sumber data.
SQL_COPT_SS_ANSI_OEM
Mengontrol konversi data ANSI ke OEM.
Nilai Atribut | Deskripsi |
---|---|
SQL_AO_OFF | (Default) Terjemahan tidak dilakukan. |
SQL_AO_ON | Terjemahan selesai. |
SQL_COPT_SS_AUTOBEGINTXN
Versi 17.6+ Saat autocommit nonaktif, mengontrol BEGIN TRANSACTION otomatis setelah ROLLBACK atau COMMIT.
Nilai Atribut | Deskripsi |
---|---|
SQL_AUTOBEGINTXN_ON | (Default) BEGIN TRANSACTION otomatis setelah ROLLBACK atau COMMIT. |
SQL_AUTOBEGINTXN_OFF | Tidak ada BEGIN TRANSACTION otomatis setelah ROLLBACK atau COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Mengontrol penggunaan Koneksi Fallback SQL Server. Yang satu ini tidak lagi didukung.
Nilai Atribut | Deskripsi |
---|---|
SQL_FB_OFF | (Default) Koneksi fallback dinonaktifkan. |
SQL_FB_ON | Koneksi fallback diaktifkan. |
Kata Kunci String Koneksi Baru dan Atribut Koneksi
Autentikasi - SQL_COPT_SS_AUTHENTICATION
Mengatur mode autentikasi yang akan digunakan saat menyambungkan ke SQL Server. Untuk informasi selengkapnya, lihat Menggunakan ID Microsoft Entra.
Nilai Kata Kunci | Nilai Atribut | Deskripsi |
---|---|---|
SQL_AU_NONE | (Default) Tidak diatur. Kombinasi atribut lain menentukan mode autentikasi. | |
SqlPassword | SQL_AU_PASSWORD | Autentikasi SQL Server dengan nama pengguna dan kata sandi. |
ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Autentikasi terintegrasi Microsoft Entra. |
ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Autentikasi kata sandi Microsoft Entra. |
ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Autentikasi Microsoft Entra Interactive. |
ActiveDirectoryMsi | SQL_AU_AD_MSI | Autentikasi identitas terkelola Microsoft Entra. Untuk identitas yang ditetapkan pengguna, UID diatur ke ID objek identitas pengguna. |
ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Autentikasi perwakilan layanan Microsoft Entra. UID diatur ke ID klien perwakilan layanan. PWD diatur ke rahasia klien. |
SQL_AU_RESET | Tidak diatur. Mengambil alih pengaturan DSN atau string koneksi apa pun. |
Catatan
Saat menggunakan Authentication
kata kunci atau atribut, tentukan Encrypt
pengaturan secara eksplisit ke nilai yang diinginkan dalam atribut string koneksi / DSN / koneksi. Lihat Menggunakan Kata Kunci String Koneksi dengan Klien Asli SQL Server untuk detailnya.
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
Mengontrol enkripsi kolom transparan (Always Encrypted). Untuk informasi selengkapnya, lihat Menggunakan Always Encrypted (ODBC).
Nilai Kata Kunci | Nilai Atribut | Deskripsi |
---|---|---|
Aktif | SQL_CE_ENABLED | Mengaktifkan Always Encrypted. |
Nonaktif | SQL_CE_DISABLED | (Default) Menonaktifkan Always Encrypted. |
SQL_CE_RESULTSETONLY | Mengaktifkan dekripsi saja (hasil dan mengembalikan nilai). |
Enkripsi
Menentukan apakah koneksi menggunakan enkripsi TLS melalui jaringan. Nilai yang mungkin adalah yes
/mandatory
(18.0+),optional
no
/ (18.0+), dan strict
(18.0+). Nilai default ada yes
di versi 18.0+ dan no
di versi sebelumnya.
Terlepas dari pengaturan untuk Encrypt
, kredensial masuk server (nama pengguna dan kata sandi) selalu dienkripsi.
Encrypt
, TrustServerCertificate
, dan pengaturan sisi Force Encryption
server memainkan peran dalam apakah koneksi dienkripsi melalui jaringan. Tabel berikut ini memperlihatkan efek pengaturan ini.
Driver ODBC 18 dan yang lebih baru
Pengaturan Enkripsi | Sertifikat Server Kepercayaan | Enkripsi Paksa Server | Hasil |
---|---|---|---|
Tidak | No | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server tidak dienkripsi. |
Tidak | Ya | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server tidak dienkripsi. |
Ya | No | Tidak | Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Ya | Ya | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Tidak | No | Ya | Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Tidak | Ya | Ya | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Ya | No | Ya | Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Ya | Ya | Ya | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Ketat | - | - | TrustServerCertificate diabaikan. Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Catatan
Ketat hanya tersedia terhadap server yang mendukung koneksi TDS 8.0.
Driver ODBC 17 dan yang lebih lama
Pengaturan Enkripsi | Sertifikat Server Kepercayaan | Enkripsi Paksa Server | Hasil |
---|---|---|---|
Tidak | No | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server tidak dienkripsi. |
Tidak | Ya | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server tidak dienkripsi. |
Ya | No | Tidak | Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Ya | Ya | Tidak | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Tidak | No | Ya | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Tidak | Ya | Ya | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
Ya | No | Ya | Sertifikat server dicentang. Data yang dikirim antara klien dan server dienkripsi. |
Ya | Ya | Ya | Sertifikat server tidak diperiksa. Data yang dikirim antara klien dan server dienkripsi. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
Mengontrol fitur Resolusi IP Jaringan Transparan, yang berinteraksi dengan MultiSubnetFailover untuk memungkinkan upaya koneksi ulang yang lebih cepat. Untuk informasi selengkapnya, lihat Menggunakan Resolusi IP Jaringan Transparan.
Nilai Kata Kunci | Nilai Atribut | Deskripsi |
---|---|---|
Aktif | SQL_IS_ON | (Default) Mengaktifkan Resolusi IP Jaringan Transparan. |
Nonaktif | SQL_IS_OFF | Menonaktifkan Resolusi IP Jaringan Transparan. |
GunakanFMTONLY
Mengontrol penggunaan SET FMTONLY untuk metadata saat menyambungkan ke SQL Server 2012 dan yang lebih baru.
Nilai Kata Kunci | Deskripsi |
---|---|
No | (Default) Gunakan sp_describe_first_result_set untuk metadata jika tersedia. |
Ya | Gunakan SET FMTONLY untuk metadata. |
Replikasi
Menentukan penggunaan login replikasi pada Driver ODBC versi 17.8 dan yang lebih baru.
Nilai Kata Kunci | Deskripsi |
---|---|
No | (Default) Login replikasi tidak digunakan. |
Ya | Pemicu dengan NOT FOR REPLICATION opsi tidak diaktifkan pada koneksi. |
RetryExec
Logika coba lagi yang dapat dikonfigurasi tersedia mulai versi 18.1. Ini secara otomatis menjalankan kembali panggilan fungsi ODBC tertentu berdasarkan kondisi yang dapat dikonfigurasi. Fitur ini dapat diaktifkan melalui string koneksi menggunakan kata kunci RetryExec, bersama dengan daftar aturan coba lagi. Setiap aturan coba lagi memiliki tiga komponen yang dipisahkan titik dua: kecocokan kesalahan, kebijakan coba lagi, dan kecocokan kueri.
Kecocokan kueri menentukan aturan coba lagi yang akan digunakan untuk eksekusi tertentu, dan dicocokkan dengan teks perintah masuk (SQLExecDirect) atau teks perintah yang disiapkan dalam objek pernyataan (SQLExecute). Jika lebih dari satu aturan cocok, aturan pertama yang cocok dalam daftar akan digunakan. Perilaku ini memungkinkan aturan untuk dicantumkan dalam rangka meningkatkan kegeneralan. Jika tidak ada aturan yang cocok, maka tidak ada coba lagi yang diterapkan.
Ketika eksekusi menghasilkan kesalahan, dan ada aturan coba lagi yang berlaku, kecocokan kesalahannya digunakan untuk menentukan apakah eksekusi harus dicoba kembali.
Nilai kata kunci RetryExec adalah daftar aturan coba lagi yang dipisahkan titik koma.
RetryExec={rule1;rule2}
Aturan coba lagi adalah sebagai berikut: <errormatch>:<retrypolicy>:<querymatch>
Kecocokan Kesalahan: Daftar kode kesalahan yang dipisahkan koma. Misalnya, menentukan 1000.2000 adalah kode kesalahan yang ingin Anda coba lagi.
Kebijakan Coba Lagi: Menentukan penundaan hingga coba lagi berikutnya. Parameter pertama adalah jumlah percobaan ulang sementara yang kedua adalah penundaan. Misalnya, 3,10+7 akan menjadi 3 percobaan mulai dari 10 dan setiap percobaan ulang berikut akan bertambah 7 detik. Jika +7 tidak ditentukan, maka setiap percobaan ulang berikut digandakan secara eksponensial.
Pencocokan Kueri: Menentukan kueri yang ingin Anda cocokkan. Jika tidak ada yang ditentukan, maka itu berlaku untuk semua kueri. Menentukan SELECT berarti untuk semua kueri yang dimulai dengan pilih.
Menggabungkan ketiga komponen di atas bersama-sama untuk digunakan dalam string koneksi adalah:
RetryExec={1000,2000:3,10+7:SELECT}
Yang berarti: "Untuk kesalahan 1000 dan 2000, pada kueri yang dimulai dengan SELECT. Coba lagi dua kali dengan penundaan awal 10 detik dan tambahkan 7 detik untuk setiap upaya berikut"
Contoh
40501,40540:4,5
Untuk kesalahan 40501 dan 40540, coba lagi hingga empat kali, dengan penundaan awal 5 detik, dan penggandaan eksponensial antara setiap coba lagi. Aturan ini berlaku untuk semua kueri.
49919:2,10+:CREATE
Untuk kesalahan 49919 pada kueri yang dimulai dengan CREATE, coba lagi paling banyak dua kali, awalnya setelah 10 detik, lalu 20 detik.
49918,40501,10928:5,10+5:SELECT c1
Untuk kesalahan, 49918, 40501, dan 10928 pada kueri yang dimulai dengan SELECT c1, coba lagi hingga lima kali, menunggu 10 detik pada coba lagi pertama dan meningkatkan tunggu 5 detik setelahnya.
Tiga aturan di atas dapat ditentukan bersama-sama dalam string koneksi sebagai berikut:
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
Aturan yang paling umum (cocok-semua) ditempatkan di akhir, untuk memungkinkan dua aturan yang lebih spesifik sebelum cocok dengan kueri masing-masing.
ClientCertificate
Menentukan sertifikat yang akan digunakan untuk autentikasi. Opsinya adalah:
Nilai Opsi | Deskripsi |
---|---|
sha1:<hash_value> |
Driver ODBC menggunakan hash SHA1 untuk menemukan sertifikat di Windows Certificate Store |
subject:<subject> |
Driver ODBC menggunakan subjek untuk menemukan sertifikat di Windows Certificate Store |
file:<file_location>[,password:<password> ] |
Driver ODBC menggunakan file sertifikat. |
Jika sertifikat dalam format PFX dan kunci privat di dalam sertifikat PFX dilindungi kata sandi, kata kunci kata sandi diperlukan. Untuk sertifikat dalam format PEM dan DER atribut ClientKey diperlukan
ClientKey
Menentukan lokasi file kunci privat untuk PEM
atau DER
sertifikat yang ditentukan oleh atribut ClientCertificate. Format:
Nilai Opsi | Deskripsi |
---|---|
file:<file_location>[,password:<password> ] |
Menentukan lokasi file kunci privat. |
Jika file kunci privat dilindungi kata sandi, kata kunci kata sandi diperlukan. Jika kata sandi berisi karakter apa pun ,
, karakter tambahan ,
ditambahkan segera setelah masing-masing karakter. Misalnya, jika kata sandi adalah a,b,c
, kata sandi yang lolos ada di string koneksi adalah a,,b,,c
.
HostnameInCertificate
Menentukan nama host yang akan diharapkan dalam sertifikat server saat enkripsi dinegosiasikan, jika berbeda dari nilai default yang berasal dari Addr/Address/Server. Opsi HostnameInCertificate diabaikan saat menggunakan opsi ServerCertificate.
IpAddressPreference
Tersedia dimulai dengan versi 18.1, opsi ini memungkinkan pengguna untuk menentukan jenis Alamat IP yang ingin mereka prioritaskan untuk koneksi. Opsi yang mungkin adalah "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]." UsePlatformDefault terhubung ke alamat dalam urutan yang disediakan oleh panggilan sistem untuk menyelesaikan nama server. Nilai defaultnya adalah IPv4First, yang sesuai dengan perilaku di versi sebelumnya.
ServerCertificate
Tersedia dimulai dengan versi 18.1, opsi ini dapat digunakan dengan mode enkripsi yang ketat. Kata kunci ServerCertificate digunakan untuk menentukan jalur ke file sertifikat yang cocok dengan sertifikat SQL Server TLS/SSL. Kecocokan dilakukan alih-alih validasi sertifikat standar (kedaluwarsa, nama host, rantai kepercayaan, dll.) Format sertifikat yang diterima adalah PEM, DER, dan CER. Jika ditentukan, sertifikat SQL Server diperiksa dengan melihat apakah ServerCertificate yang disediakan sama persis.
SQL_COPT_SS_ACCESS_TOKEN
Memungkinkan penggunaan token akses Microsoft Entra untuk autentikasi. Untuk informasi selengkapnya, lihat Menggunakan ID Microsoft Entra.
Nilai Atribut | Deskripsi |
---|---|
NULL | (Default) Tidak ada token akses yang disediakan. |
ACCESSTOKEN* | Penunjuk ke token akses. |
SQL_COPT_SS_CEKEYSTOREDATA
Berkomunikasi dengan pustaka penyedia keystore yang dimuat. Lihat Mengontrol enkripsi kolom transparan (Always Encrypted). Atribut ini tidak memiliki nilai default. Untuk informasi selengkapnya, lihat Penyedia Keystore Kustom.
Nilai Atribut | Deskripsi |
---|---|
CEKEYSTOREDATA * | Struktur data komunikasi untuk pustaka penyedia keystore |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Memuat pustaka penyedia keystore untuk Always Encrypted, atau mengambil nama pustaka penyedia keystore yang dimuat. Untuk informasi selengkapnya, lihat Penyedia Keystore Kustom. Atribut ini tidak memiliki nilai default.
Nilai Atribut | Deskripsi |
---|---|
Char* | Jalur ke pustaka penyedia keystore |
SQL_COPT_SS_ENLIST_IN_XA
Untuk mengaktifkan transaksi XA dengan Prosesor Transaksi (TP) yang mematuhi XA, aplikasi perlu memanggil SQLSetConnectAttr dengan SQL_COPT_SS_ENLIST_IN_XA dan pointer ke XACALLPARAM
objek. Opsi ini didukung pada Windows (17.3+), Linux, dan macOS.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Untuk mengaitkan transaksi XA dengan koneksi ODBC saja, berikan TRUE atau FALSE dengan SQL_COPT_SS_ENLIST_IN_XA alih-alih pointer saat memanggil SQLSetConnectAttr
. Pengaturan ini hanya valid pada Windows dan tidak dapat digunakan untuk menentukan operasi XA melalui aplikasi klien.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
Nilai | Deskripsi | Platform |
---|---|---|
Objek XACALLPARAM* | Penunjuk ke XACALLPARAM objek. |
Windows, Linux, dan macOS |
BENAR | Mengaitkan transaksi XA dengan koneksi ODBC. Semua aktivitas database terkait dilakukan di bawah perlindungan transaksi XA. | Windows |
SALAH | Memisahkan transaksi dengan koneksi ODBC. | Windows |
Untuk informasi selengkapnya tentang transaksi XA, lihat Menggunakan Transaksi XA.
SQL_COPT_SS_LONGASMAX
Memungkinkan data jenis panjang dikirim ke server sebagai data jenis maks.
Nilai Atribut | Deskripsi |
---|---|
No | (Default) Jangan mengonversi jenis panjang ke jenis maks saat mengirim. |
Ya | Mengonversi data dari jenis panjang ke jenis maks saat mengirim. |
SQL_COPT_SS_SPID
Mengambil ID proses server koneksi. Properti ini setara dengan variabel T-SQL @@SPID , kecuali tidak dikenakan pulang pergi tambahan ke server.
Nilai Atribut | Deskripsi |
---|---|
DWORD | SPID |