SQL Server için Microsoft ODBC Sürücüsü

ODBC sürücüsü indirme

ODBC, C ve C++ dillerinde yazılmış uygulamalar için yerel bir veri erişimi uygulama programlama arayüzüdür (API). Microsoft ODBC Driver for SQL Server, SQL Server’a, Azure SQL Veritabanı’e, Azure SQL Yönetilen Örneği’a, Azure Synapse Analytics’e ve Microsoft Fabric’teki SQL veritabanına bağlanır. Her sürücü sürümünün desteklediği veritabanı sürümleri için SQL sürüm uyumluluğuna bakınız.

Uygulamanız ODBC sürücü yöneticisini çağırır; bu yönetici sürücüyü yükler ve ODBC çağrılarını ona iletir. Windows'ta Windows ODBC Driver Manager ve Linux ile macOS'ta unixODBC kullanın.

ODBC kullanabilen diğer diller COBOL, Perl, PHP ve Python'dır. ODBC, veri entegrasyon senaryolarında yaygın olarak kullanılır ve Microsoft Drivers for PHP for SQL Server bu sürücü üzerine inşa edilmiştir.

sqlcmd'nin ODBC varyantı ve bcp aracı bu sürücüyü kullanır, ancak ayrı ayrı yüklenirler: Linux ve macOS'ta mssql-tools18 paketi, Windows'ta ise Microsoft Command Line Utilities. sqlcmd'nin Go versiyonu bu sürücüyü kullanmıyor. Transact-SQL (T-SQL) ifadeleri, sistem prosedürleri ve script dosyalarını çalıştırmak için sqlcmd kullanın. BCP'yi kullanarak verileri SQL Server örneği ile bir veri dosyası arasında, her iki yönde de toplu kopyalayabilirsiniz.

Başlangıç noktanızı seçin

Azure SQL için üretim temeli

Bu tam C++17 programını Azure barındırılan bir uygulama için başlangıç noktası olarak kullanın. Bağlantı kurar, SELECT 1 çalıştırır, sonucu kontrol eder ve ODBC tutamaçlarını serbest bırakır. Oluşturmadan önce Sürücü 18'i ve platformun ODBC geliştirme dosyalarını yükleyin. Ön koşullar için ODBC sürücüsü ile C ve C++ uygulamaları geliştirme bölümüne bakın.

Uygulamanın ortamında ODBC_CONNECTION_STRING değerini tam bağlantı dizeniz olarak ayarlayın. Aşağıdaki örnek, sistem tarafından atanan yönetilen bir kimlik kullanır. Ana bilgisayarda bu kimlik etkinleştirilmiş olmalıdır ve veritabanı ona erişim izni vermelidir. Ana bilgisayar gereksinimleri, kullanıcı tarafından atanan kimlikler ve yerel geliştirme kimlik doğrulaması için bkz. Microsoft Entra ID'yi ODBC sürücüsüyle kullanın.

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=ActiveDirectoryMsi;Encrypt=strict;ConnectRetryCount=3;ConnectRetryInterval=2;

Encrypt=strict Tabular Data Stream (TDS) 8.0'ı destekleyen bir uç nokta gerektirir. Aksi takdirde kullanın Encrypt=yes;TrustServerCertificate=no. İstemcinin güvendiği ve adı sunucuyla eşleşen bir sertifikayı yapılandırın. Kurulum ve doğrulama için bkz. Bağlantı şifreleme sorun giderme.

Kimlik bilgilerini kaynak dosyalardan ve shell geçmişinden uzak tutun. Ortam değişkenini ayarlama komutları için Bağlantıyı Yapılandır bölümüne bakın. Linux ve macOS'ta, değerini UTF-8 olarak belirtin. Aşağıdaki programı odbc-baseline.cpp olarak kaydedin:

#ifdef _WIN32
#include <windows.h>
#else
#include <iconv.h>
#endif
#include <sql.h>
#include <sqlext.h>

#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <iostream>
#include <random>
#include <stdexcept>
#include <string>
#include <thread>
#include <vector>

struct Handles {
    SQLHENV env = SQL_NULL_HENV;
    SQLHDBC dbc = SQL_NULL_HDBC;
    SQLHSTMT stmt = SQL_NULL_HSTMT;
    bool connected = false;

    ~Handles() {
        if (stmt) SQLFreeHandle(SQL_HANDLE_STMT, stmt);
        if (connected) SQLDisconnect(dbc);
        if (dbc) SQLFreeHandle(SQL_HANDLE_DBC, dbc);
        if (env) SQLFreeHandle(SQL_HANDLE_ENV, env);
    }
};

bool logDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    bool retry = false;
    bool permanent = false;
    for (SQLSMALLINT record = 1; ; ++record) {
        SQLWCHAR state[6] = {};
        SQLWCHAR message[1024] = {};
        SQLINTEGER native = 0;
        SQLRETURN rc = SQLGetDiagRecW(type, handle, record, state, &native,
                                     message, 1024, nullptr);
        if (rc == SQL_NO_DATA) break;
        if (!SQL_SUCCEEDED(rc)) {
            std::cerr << "event=diagnostics_failed rc=" << rc << '\n';
            return false;
        }
        std::string sqlstate;
        for (int i = 0; i < 5; ++i) {
            sqlstate += static_cast<char>(state[i]);
        }
        std::cerr << "event=odbc_diagnostic sqlstate=" << sqlstate
                  << " native_error=" << native << '\n';
        permanent |= sqlstate.substr(0, 2) == "28" ||
                     sqlstate.substr(0, 2) == "IM" ||
                     sqlstate == "HY024" || sqlstate == "HY092";
        retry |= sqlstate == "08S01" || sqlstate == "HYT00" ||
                 sqlstate == "HYT01";
        switch (native) {
            case 10928: case 10929: case 10936:
            case 40197: case 40501: case 40613:
            case 49918: case 49919: case 49920:
                retry = true;
        }
    }
    return retry && !permanent;
}

void requireSuccess(SQLRETURN rc, SQLSMALLINT type, SQLHANDLE handle,
                    const char* operation) {
    if (rc == SQL_SUCCESS) return;
    logDiagnostics(type, handle);
    if (!SQL_SUCCEEDED(rc)) throw std::runtime_error(operation);
}

std::vector<SQLWCHAR> readConnectionString() {
    static_assert(sizeof(SQLWCHAR) == 2, "Use a driver manager with 16-bit SQLWCHAR");
#ifdef _WIN32
    size_t length = 0;
    if (_wgetenv_s(&length, nullptr, 0, L"ODBC_CONNECTION_STRING") != 0 ||
        length == 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    }
    std::vector<wchar_t> raw(length);
    if (_wgetenv_s(&length, raw.data(), raw.size(), L"ODBC_CONNECTION_STRING") != 0) {
        throw std::runtime_error("Cannot read ODBC_CONNECTION_STRING");
    }
    std::vector<SQLWCHAR> result(raw.begin(), raw.end() - 1);
#else
    const char* raw = std::getenv("ODBC_CONNECTION_STRING");
    if (!raw) throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    iconv_t converter = iconv_open("UTF-16LE", "UTF-8");
    if (converter == reinterpret_cast<iconv_t>(-1)) {
        throw std::runtime_error("Cannot create UTF-8 converter");
    }
    size_t inputBytes = std::strlen(raw);
    std::vector<SQLWCHAR> result(inputBytes + 1);
    char* input = const_cast<char*>(raw);
    char* output = reinterpret_cast<char*>(result.data());
    size_t outputBytes = result.size() * sizeof(SQLWCHAR);
    const size_t capacity = outputBytes;
    size_t status = iconv(converter, &input, &inputBytes, &output, &outputBytes);
    int closeStatus = iconv_close(converter);
    if (status == static_cast<size_t>(-1) || inputBytes != 0 || closeStatus != 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING must be valid UTF-8");
    }
    result.resize((capacity - outputBytes) / sizeof(SQLWCHAR));
#endif
    if (result.empty() || result.size() >= 32767) {
        throw std::runtime_error("Invalid ODBC_CONNECTION_STRING length");
    }
    result.push_back(0);
    return result;
}

void connectWithRetry(SQLHDBC dbc, std::vector<SQLWCHAR>& connectionString) {
    constexpr int maxAttempts = 4;
    std::mt19937 random{std::random_device{}()};
    std::uniform_int_distribution<int> jitter{0, 250};
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        requireSuccess(SQLSetConnectAttr(
            dbc, SQL_ATTR_LOGIN_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{30}), 0),
            SQL_HANDLE_DBC, dbc, "Set login timeout");
        SQLRETURN rc = SQLDriverConnectW(
            dbc, nullptr, connectionString.data(), SQL_NTS,
            nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            if (rc == SQL_SUCCESS_WITH_INFO) logDiagnostics(SQL_HANDLE_DBC, dbc);
            std::cout << "event=connected attempt=" << attempt << '\n';
            return;
        }
        bool transient = logDiagnostics(SQL_HANDLE_DBC, dbc);
        if (!transient || attempt == maxAttempts) {
            throw std::runtime_error("Connect failed");
        }
        auto delay = std::chrono::milliseconds{
            (1 << (attempt - 1)) * 10000 + jitter(random)};
        std::cerr << "event=connect_retry attempt=" << attempt
                  << " delay_ms=" << delay.count() << '\n';
        std::this_thread::sleep_for(delay);
    }
}

int main() {
    try {
        auto connectionString = readConnectionString();
        Handles handles;
        if (!SQL_SUCCEEDED(SQLAllocHandle(
                SQL_HANDLE_ENV, SQL_NULL_HANDLE, &handles.env))) {
            throw std::runtime_error("Allocate environment");
        }
        requireSuccess(SQLSetEnvAttr(
            handles.env, SQL_ATTR_ODBC_VERSION,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{SQL_OV_ODBC3}), 0),
            SQL_HANDLE_ENV, handles.env, "Set ODBC version");
        requireSuccess(SQLAllocHandle(SQL_HANDLE_DBC, handles.env, &handles.dbc),
                       SQL_HANDLE_ENV, handles.env, "Allocate connection");
        connectWithRetry(handles.dbc, connectionString);
        handles.connected = true;
        requireSuccess(SQLAllocHandle(SQL_HANDLE_STMT, handles.dbc, &handles.stmt),
                       SQL_HANDLE_DBC, handles.dbc, "Allocate statement");
        requireSuccess(SQLSetStmtAttr(
            handles.stmt, SQL_ATTR_QUERY_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{10}), 0),
            SQL_HANDLE_STMT, handles.stmt, "Set query timeout");
        SQLWCHAR query[] = {'S', 'E', 'L', 'E', 'C', 'T', ' ', '1', 0};
        requireSuccess(SQLExecDirectW(handles.stmt, query, SQL_NTS),
                       SQL_HANDLE_STMT, handles.stmt, "Execute probe");
        requireSuccess(SQLFetch(handles.stmt),
                       SQL_HANDLE_STMT, handles.stmt, "Fetch probe");
        SQLINTEGER value = 0;
        SQLLEN indicator = 0;
        requireSuccess(SQLGetData(handles.stmt, 1, SQL_C_SLONG,
                                 &value, sizeof(value), &indicator),
                       SQL_HANDLE_STMT, handles.stmt, "Read probe");
        if (indicator == SQL_NULL_DATA || value != 1) {
            throw std::runtime_error("Unexpected probe result");
        }
        std::cout << "event=ready result=" << value << '\n';
        return 0;
    } catch (const std::exception& error) {
        std::cerr << "event=failed operation=\"" << error.what() << "\"\n";
        return 1;
    }
}

Program, en fazla dört bağlantı denemesinin her biri için 30 saniyelik bağlantı zaman aşımı süresi ve 10 saniyelik sorgu zaman aşımı süresi ister. Başarısız geçici bağlantı denemeleri arasında 10, 20 ve 40 saniye bekler, her biri 0 ila 250 milisaniye arasında rastgele jitter içerir. Bu sınırlar, kimlik doğrulama için katı bir genel süre sınırı koymaz. Örnek, seçilmiş geçici bağlantı hatalarını sınıflandırır; politikayı, Azure SQL geçici hata kataloğunu kullanarak iş yükünüze uyarlayın. Uygulama komutlarını veya yazma işlemlerini yeniden denemez.

ConnectRetryCount ve ConnectRetryInterval, boşta dururken kesilen uygun bağlantılar için bağlantı dayanıklılığını yapılandırır. İlk bağlantıyı tekrar denemez veya uygulama komutlarını yeniden yürütmezler. Boşta geri dönüş gecikmelerini, sorgu zaman aşımı süresinden daha kısa tutun. Örnek, bağlantı dizileri veya tam tanı mesajları yerine SQLSTATE değerlerini ve yerel hata sayılarını kaydeder. Sorun gidermek için mesaj metnine ihtiyacınız varsa, bunu korumalı bir tanı kaydına kaydedin.

Baseline’i oluştur ve çalıştır

Uygulamanızın işlemci mimarisine uygun bir derleyici ortamı kullanın. Windows'ta, komutları Developer PowerShell for Visual Studio'da çalıştırın. Linux ve macOS'ta, derleyiciniz ve unixODBC geliştirme dosyalarınız olan bir shell kullanın.

cl /nologo /std:c++17 /EHsc /W4 odbc-baseline.cpp odbc32.lib
.\odbc-baseline.exe

Başarılı bir ilk bağlantı aşağıdaki çıktıyı yazdırır. Ek tanı kayıtları da ortaya çıkabilir.

event=connected attempt=1
event=ready result=1

Bitirdiğinizde temizleyinODBC_CONNECTION_STRING: PowerShell'de unset ODBC_CONNECTION_STRING, Bash veya Zsh'de Remove-Item Env:\ODBC_CONNECTION_STRING kullanın.

Erişilebilirlik grubu dinleyicileri ve failover ayarları için Yüksek erişilebilirlik ve felaket kurtarma kullanın.

Temel özellikler

  • Çapraz platform: Windows, Linux ve macOS'ta aynı API.
  • Microsoft Entra ID kimlik doğrulaması: Yönetilen kimlik, hizmet sorumlusu ve tümleşik kimlik doğrulama, ayrıca Windows'ta etkileşimli kimlik doğrulama. Mevcut yöntemler ana bilgisayar ve veritabanı yapılandırmasına bağlıdır.
  • Sıkı şifreleme: TDS 8.0 bağlantıları, sürüm 18 ve sonraki sürümlerde tam sertifika doğrulaması ile sağlanır.
  • Her Zaman Şifreli: Hassas sütunlar için istemci tarafı şifreleme, özel anahtar deposu sağlayıcılarını desteklemek.
  • Bağlantı dayanıklılığı: Boştayken kesilen bir bağlantının şeffaf olarak yeniden kurulması.
  • Yüksek kullanılabilirlik: MultiSubnetFailover ile kullanılabilirlik grubu dinleyicisi desteği.
  • Veri sınıflandırması: Sınıflandırılmış sütunlar için duyarlılık meta verileri.
  • Vektör veri tipi: Vektör tipi için yerel destek.
  • Dağıtık işlemler: Microsoft Dağıtılmış İşlem Düzenleyicisi (MSDTC) aracılığıyla XA işlem desteği.
  • Yardımcı araçlar: sqlcmd ve bcp, ayrı ayrı kurulmuş.

Başlayın

Makale Description
SQL Server için ODBC Sürücüsünü indirme Desteklenen her sürücü sürümü için kurulum ve paket indirmeleri, üç platformda da var.
ODBC sürücüsüyle C ve C++ uygulamaları geliştirin Hangi başlıkların dahil edileceği, hangi sırayla kullanılacağı, hangi kütüphanelerin bağlanacağı ve asenkron yürütme ile iş parçacıkları arasında nasıl seçim yapılacağı.
C++ ile veritabanına bağlanın ve sorgulayın Bağlanan, sorgu çalıştıran ve sonuçları okuyan, böylece kurulumunuzu baştan uca onaylayabilmeniz için tam bir C++ örneği.
Destek yaşam döngüsü Hangi sürücü sürümlerinin hâlâ desteklenmeye devam ettiği ve her birinin destek kapsamından çıktığı tarih.
Başlıca sürüm farklılıkları Şifreleme varsayılan değişikliğinden başlayarak 17. sürümden 18. sürüme geçtiğinizde ne bozuluyor?

Sürücüyü yükleme

Makale Description
Sistem gereksinimleri, kurulum ve sürücü dosyaları (Windows) Desteklenen Windows sürümleri, sessiz dağıtım için kurulumcu komut satırı ve her sürücü dosyasının diske indiği yer.
Sistem gereksinimleri (Linux ve macOS) Her sürücü sürümünün desteklediği Linux dağıtımları ve macOS sürümleri ile SQL Server sürüm uyumluluğu.
ODBC sürücüsünü Linux'a yükleyin Alpine, Debian, Red Hat, SUSE, Ubuntu ve Azure Linux için paket yöneticisi adımları, ayrıca çevrimdışı kurulum ve sürücü dosya konumları.
ODBC sürücüsünü macOS'a yükleyin macOS için Homebrew tap ve formula adımları; 18, 17 veya 13.1 sürümünün nasıl kurulacağı da dahil.
UnixODBC sürücü yöneticisini (Linux ve macOS) kur Linux ve macOS'ta ODBC sürücüsünü yükleyen sürücü yöneticisi unixODBC'yi kur veya yükseltin.

Yapılandırma ve bağlanma

Makale Description
DSN ve bağlantı dizesi anahtar sözcükleri ve öznitelikleri Her biri için kabul edilen değerlerle birlikte bağlantı dizesi anahtar kelimeleri, DSN girişleri ve SQLSetConnectAttr niteliklerinin tam kataloğu.
Bağlantı dizisi anahtar kelimeleri ve veri kaynağı adları (Linux ve macOS) odbc.ini ve odbcinst.ini'in Linux ve macOS'ta bir DSN'yi nasıl tanımladığı, ayrıca bu platformlara özgü Taşıma Katmanı Güvenliği (TLS) ve İletim Kontrol Protokolü (TCP) keep-alive ayarları.
ODBC Veri Kaynağı Yöneticisi DSN (Windows) Bir veri kaynağını bağlantı string yerine Windows kullanıcı arayüzü üzerinden yapılandırın.
Sürücüye duyarlı bağlantı havuzu (Windows) Hangi bağlantı dizesi anahtar sözcükleri ve öznitelikleri bir bağlantıyı ayrı bir havuza yerleştirir ve hangileri bağlantıyı sıfırlamak için ek bir gidiş-dönüş gerektirir.

Doğrulama ve güvence

Makale Description
ODBC sürücüsü ile Microsoft Entra ID'yi kullanın Her Authentication anahtar kelime değeri, yönetilen kimlik ve hizmet prensibinden etkileşimli ve entegre hale kadar, her birinin ihtiyaç duyduğu kurulumla birlikte.
ODBC sürücüsüyle Her Zaman Şifrelenmiş Kullan Hassas sütun değerlerini veritabanına göndermeden önce, sürücünün API özeti ve belgelenmiş sınırlamalarıyla birlikte şifreleyin.
Veri sınıflandırma Sunucunun gizli sütunlara eklediği hassasiyet etiketlerini okuyun, böylece uygulamanız kendi veri koruma politikasını uygulayabilir.
Entegre kimlik doğrulama kullanın (Linux ve macOS) Kerberos'u Linux veya macOS istemcisi Windows Server girişi yerine Windows kimlik bilgileriyle bağlanacak şekilde yapılandırın.

Yüksek kullanılabilirlik ve dayanıklılık

Makale Description
Bağlantı dayanıklılığı ConnectRetryCount ve ConnectRetryInterval'in, sunucu boşta beklerken bağlantıyı keserse bağlantıyı nasıl yeniden kurduğu ve kurtarma mümkün olmadığında sürücünün döndürdüğü IMCxx hatalar.
Yüksek kullanılabilirlik ve olağanüstü durum kurtarma Kullanılabilirlik grubu dinleyicisi üzerinden bağlanın ve failover'ın alt ağ zaman aşımında durmaması için kullanın MultiSubnetFailover .
Şeffaf ağ IP çözünürlüğü kullanın Eski TransparentNetworkIPResolution geri dönüş mekanizması birden fazla İnternet Protokolü (IP) adresi arasında bağlantı girişimlerini nasıl sıralıyor ve neden MultiSubnetFailover onun yerini alıyor.

Verilerle çalışma

Makale Description
Vektör veri türü vector türünü, yerel C temsili ve toplu kopyalama desteği dahil olmak üzere bağlayın, gönderin ve alın.
DTC ile XA işlemlerini kullanın Windows Server, Linux veya macOS üzerinde Microsoft Dağıtılmış İşlem Düzenleyicisi aracılığıyla dağıtık bir işlem içinde SQL Server'ı kaydedin.
Programlama yönergeleri (Linux ve macOS) Linux ve macOS programlama rehberliği, özellik durumu, karakter kümesiyle ilgili dikkat edilmesi gerekenler, OpenSSL ve Alpine Linux gibi bilgileri bulabilirsiniz.

Tanılama ve sorun giderme

Makale Description
Bağlantı şifreleme sorun giderme Varsayılan olarak şifrelediği için 18. sürümde ortaya çıkan sertifika ve şifreleme hatalarını düzeltin.
Veri erişim izleme (Linux ve macOS) Sürücü takibi aç ve uygulamanızın gerçekten yaptığı çağrıları görmek istediğinizde bir log dosyası yakalayın.
Bilinen sorunlar (Linux ve macOS) Kusurlar ve bunların çözüm yolları doğrulandı. Destek davası açmadan önce buraya bakın.
Sıkça Sorulan Sorular (Linux ve macOS) Linux ve macOS'ta sürücüyle ilgili en sık karşılaşılan sorulara kısa cevaplar.

Sürüm notları ve hata düzeltmeleri

Makale Description
Windows için sürüm notları Her Windows sürücü sürümünde yeni özellikler, davranış değişiklikleri ve düzeltmeler.
Linux ve macOS için sürüm notları Her Linux ve macOS sürücü sürümünde yeni özellikler, davranış değişiklikleri ve düzeltmeler.
SQL Server araçları için sürüm notları Linux ve macOS'ta sürücüden ayrı yüklenen sqlcmd ve bcp yardımcı araçlarında değişiklikler.

Reference

Makale Description
Windows'ta ODBC sürücüsü Sürücünün Windows'ta neyi desteklediğine dair sürüm bazında bir özet ve Windows'a özgü makalelerin bir dizini.
Windows'ta ODBC sürücüsünün özellikleri Hangi sürüm Windows'un her özelliğini ve bununla birlikte gelen davranış değişikliklerini tanıttı.

Özellik isteme

Bir özellik talep etmek için SQL Server geri bildirimi aracılığıyla bir fikir gönderin.

İlgili içerik

  • Son güncelleştirme: