Microsoft ODBC Driver untuk SQL Server

Unduh driver ODBC

ODBC adalah API akses data asli utama untuk aplikasi yang ditulis dalam C dan C++ untuk SQL Server. Microsoft ODBC Driver untuk SQL Server terhubung ke SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, dan database SQL Microsoft Fabric. Untuk versi database yang didukung setiap rilis driver, lihat kompatibilitas versi SQL.

Bahasa lain yang dapat menggunakan ODBC termasuk COBOL, Perl, PHP, dan Python. ODBC banyak digunakan dalam skenario integrasi data, dan Microsoft Drivers untuk PHP untuk SQL Server dibangun di atas driver ini.

Utilitas sqlcmd dan bcp bekerja dengan driver ini, tetapi mereka menginstal secara terpisah: mssql-tools18 paket di Linux dan macOS, serta Microsoft Command Line Utilities di Windows. Gunakan sqlcmd untuk menjalankan pernyataan Transact-SQL (T-SQL), prosedur sistem, dan file skrip. Gunakan bcp untuk menyalin data secara massal antara instance SQL Server dan file data, ke kedua arah.

Pilih titik awal Anda

Garis besar produksi untuk Azure SQL

Gunakan cuplikan ini sebagai titik awal untuk koneksi Azure SQL berorientasi produksi. Aplikasi ini memuat nama server dan nama database dari konfigurasi aplikasi, mengautentikasi dengan identitas terkelola sehingga tidak ada rahasia yang muncul di string koneksi, dan mengaktifkan enkripsi Tabular Data Stream (TDS) 8.0 dengan validasi sertifikat penuh. Ini menetapkan batas waktu login untuk setiap percobaan, dan mencoba lagi saat terjadi kegagalan sementara dengan backoff eksponensial dan jitter.

Cuplikan C++ dalam artikel ini tidak menyertakan direktif include, alokasi handle, dan fungsi bantu logging demi keringkasan.

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount dan ConnectRetryInterval mengaktifkan ketahanan koneksi idle, yang secara transparan memulihkan koneksi yang terputus saat idle. Mereka tidak mencoba ulang koneksi awal, karena itu cuplikan kode ini juga menerapkan mekanisme percobaan ulang di tingkat aplikasi. Simpan keduanya.

ODBC melaporkan diagnostik melalui SQLGetDiagRec, alih-alih hanya melalui kode pengembalian, jadi klasifikasikan kegagalan sebelum mencoba lagi. Kesalahan autentikasi atau konfigurasi kemudian gagal seketika alih-alih menghabiskan seluruh anggaran percobaan ulang.

Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:

Untuk katalog kesalahan sementara Azure SQL, lihat kode kesalahan gangguan sementara.

Fitur utama

  • Multiplatform: API yang sama di Windows, Linux, dan macOS.
  • Autentikasi Microsoft Entra ID: Koneksi tanpa kata sandi dengan alur identitas terkelola, prinsipal layanan, interaktif, dan terintegrasi.
  • Enkripsi ketat: Koneksi TDS 8.0 dengan validasi sertifikat penuh pada versi 18 dan versi berikutnya.
  • Selalu Terenkripsi: Enkripsi sisi klien untuk kolom sensitif, dengan dukungan untuk penyedia keystore kustom.
  • Ketahanan koneksi: Pemulihan transparan dari koneksi yang terputus saat tidak aktif.
  • Ketersediaan tinggi: Dukungan pendengar grup ketersediaan dengan MultiSubnetFailover.
  • Klasifikasi data: Metadata sensitivitas untuk kolom yang diklasifikasikan.
  • Tipe data vektor: Dukungan native untuk tipe vektor .
  • Transaksi terdistribusi: Dukungan transaksi XA melalui Koordinator Transaksi Terdistribusi Microsoft (MSDTC).
  • Alat pendamping: sqlcmd dan bcp, diinstal secara terpisah.

Get started

Article Deskripsi
Unduh ODBC Driver untuk SQL Server Instalasi dan unduhan paket untuk setiap versi driver yang didukung, di ketiga platform.
Hubungkan ke dan kueri database dengan C++ Contoh C++ lengkap yang terhubung, menjalankan kueri, dan membaca hasil, sehingga Anda dapat mengonfirmasi pengaturan Anda secara end-to-end.
Siklus hidup dukungan Versi driver mana yang masih didukung dan tanggal berakhirnya dukungan untuk masing-masing versi.
Perbedaan versi utama Apa yang rusak saat Anda berpindah dari versi 17 ke versi 18, dimulai dengan perubahan default enkripsi.

Pasang driver

Article Deskripsi
Persyaratan sistem, instalasi, dan file driver (Windows) Versi Windows yang didukung, baris perintah penginstal untuk penerapan tanpa interaksi, dan lokasi setiap file driver di disk.
Persyaratan sistem (Linux dan macOS) Distribusi Linux dan rilis macOS mana yang didukung oleh setiap versi driver, ditambah kompatibilitas versi SQL Server.
Instal driver ODBC di Linux Langkah-langkah pengelola paket untuk Alpine, Debian, Red Hat, SUSE, Ubuntu, dan Azure Linux, serta instalasi offline dan lokasi file driver.
Instal driver ODBC di macOS Langkah-langkah Homebrew tap dan formula untuk macOS, termasuk cara menginstal versi 18, 17, atau 13.1.
Instal pengelola driver unixODBC (Linux dan macOS) Instal atau tingkatkan unixODBC, pengelola driver yang memuat driver ODBC di Linux dan macOS.

Mengonfigurasi dan menyambungkan

Article Deskripsi
DSN dan kata kunci serta atribut string koneksi Katalog lengkap kata kunci string koneksi, entri DSN, dan atribut SQLSetConnectAttr, beserta nilai yang diterima untuk masing-masing.
Kata kunci string koneksi dan nama sumber data (Linux dan macOS) Bagaimana odbc.ini dan odbcinst.ini mendefinisikan DSN di Linux dan macOS, ditambah pengaturan TLS dan TCP keep-alive yang spesifik untuk platform tersebut.
Administrator Sumber Data ODBC DSN (Windows) Setiap opsi pada halaman wizard DSN Windows, saat Anda mengonfigurasi sumber data melalui antarmuka pengguna (UI), bukan melalui string koneksi.
Pooling koneksi berdasarkan driver (Windows) Kata kunci dan atribut string koneksi mana yang menempatkan koneksi ke poolnya sendiri, dan mana yang membutuhkan biaya perjalanan pulang-pergi ekstra untuk direset.

Autentikasi dan amankan

Article Deskripsi
Gunakan Microsoft Entra ID dengan driver ODBC Setiap nilai kata kunci Authentication, dari managed identity dan service principal hingga interaktif dan terpadu, beserta pengaturan yang diperlukan untuk masing-masing.
Gunakan Selalu Terenkripsi dengan driver ODBC Enkripsi kolom sensitif dalam proses klien sehingga plaintext tidak pernah sampai ke server, dengan ringkasan API driver dan keterbatasan yang terdokumentasi.
Klasifikasi data Baca label sensitivitas yang dilampirkan server pada kolom rahasia, sehingga aplikasi Anda dapat menegakkan kebijakan perlindungan data sendiri.
Gunakan autentikasi terintegrasi (Linux dan macOS) Konfigurasikan Kerberos agar klien Linux atau macOS dapat terhubung dengan kredensial Windows daripada login SQL Server.

Ketersediaan dan ketahanan tinggi

Article Deskripsi
Ketahanan koneksi Bagaimana ConnectRetryCount dan ConnectRetryInterval memulihkan koneksi ketika server memutus koneksi tersebut saat tidak aktif, dan IMCxx kesalahan yang dikembalikan driver ketika pemulihan tidak dimungkinkan.
Ketersediaan tinggi dan pemulihan bencana Hubungkan melalui listener grup ketersediaan dan gunakan MultiSubnetFailover agar failover tidak tersendat karena waktu tunggu subnet.
Gunakan resolusi IP jaringan yang transparan Bagaimana mekanisme fallback lama TransparentNetworkIPResolution mengurutkan percobaan koneksi ke beberapa alamat IP, dan mengapa MultiSubnetFailover menggantikannya.

Bekerja dengan data

Article Deskripsi
Jenis data vektor Ikat, kirim, dan ambil tipe vektor, termasuk representasi C aslinya dan dukungan penyalinan massal.
Gunakan transaksi XA dengan DTC Daftarkan SQL Server dalam transaksi terdistribusi melalui Koordinator Transaksi Terdistribusi Microsoft di Windows, Linux, atau macOS.
Pedoman pemrograman (Linux dan macOS) Fitur mana yang didukung driver di Linux dan macOS, yang tidak, serta bagaimana penanganan set karakter dan OpenSSL berbeda dengan Windows.

Mendiagnosis dan memecahkan masalah

Article Deskripsi
Pemecahan masalah enkripsi koneksi Perbaiki kesalahan sertifikat dan enkripsi yang ditampilkan oleh versi 18 karena menggunakan enkripsi secara default.
Pelacakan akses data (Linux dan macOS) Aktifkan driver tracing dan tangkap file log saat Anda perlu melihat panggilan yang sebenarnya dilakukan aplikasi Anda.
Masalah yang diketahui (Linux dan macOS) Cacat yang dikonfirmasi dan solusi alternatifnya. Periksa di sini sebelum Anda mengajukan permintaan dukungan.
Pertanyaan yang sering diajukan (Linux dan macOS) Jawaban singkat untuk pertanyaan yang paling sering muncul tentang driver di Linux dan macOS.

Catatan rilis dan perbaikan bug

Article Deskripsi
Catatan rilis untuk Windows Fitur baru, perubahan perilaku, dan perbaikan di setiap rilis driver Windows.
Catatan rilis untuk Linux dan macOS Fitur baru, perubahan perilaku, dan perbaikan di setiap rilis driver Linux dan macOS.
Catatan rilis untuk alat SQL Server Perubahan pada utilitas sqlcmd dan bcp , yang diinstal terpisah dari driver di Linux dan macOS.

Reference

Article Deskripsi
Driver ODBC di Windows Ringkasan versi demi versi tentang apa yang didukung driver di Windows, serta indeks artikel khusus Windows.
Fitur driver ODBC di Windows Rilis mana yang memperkenalkan setiap fitur Windows, plus perubahan perilaku yang menyertainya.

Konten terkait

  • Last updated on