Driver Microsoft ODBC per SQL Server

Scaricare il driver ODBC

ODBC è l'API di accesso ai dati nativa principale per le applicazioni scritte in C e C++ per SQL Server. Il driver Microsoft ODBC per SQL Server si collega a SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics e database SQL in Microsoft Fabric. Per le versioni del database supportate da ogni release del driver, vedi compatibilità con le versioni SQL.

Altri linguaggi che possono usare ODBC sono COBOL, Perl, PHP e Python. ODBC è ampiamente utilizzato in scenari di integrazione dei dati, e i driver Microsoft per PHP per SQL Server sono basati su questo driver.

Le utility sqlcmd e bcp funzionano con questo driver, ma si installano separatamente: il mssql-tools18 pacchetto su Linux e macOS, e le utility Microsoft Command Line su Windows. Usa sqlcmd per eseguire istruzioni Transact-SQL (T-SQL), procedure di sistema e file script. Usa bcp per copiare dati in massa tra un'istanza di SQL Server e un file dati, in entrambe le direzioni.

Scegliere il punto di partenza

• Per installare il driver, vai su Requisiti di sistema, file di installazione e driver per Windows, oppure installa il driver ODBC su Linux, installa il driver ODBC su macOS e installa il gestore driver unixODBC.
• Per scrivere la tua prima applicazione, vai a Connetterti a un database ed eseguire query con C++ e Parole chiave e attributi DSN e della stringa di connessione.
• Per connettersi ad Azure SQL con autenticazione senza password, vai su Usa Microsoft Entra ID con il driver ODBC.
• Per rendere resiliente un'app esistente agli errori temporanei, vai a Resilienza della connessione e Alta disponibilità e ripristino di emergenza.
• Per eseguire l’aggiornamento dalla versione 17, vai a Differenze tra versioni principali e Risoluzione dei problemi di crittografia della connessione.
• Per diagnosticare un problema di connessione o di query, vai su Risoluzione problemi di crittografia delle connessioni e Problemi noti (Linux e macOS).

Baseline di produzione per Azure SQL

Usare questo frammento di codice come punto di partenza per una connessione Azure SQL orientata alla produzione. Carica il nome del server e il nome del database dalla configurazione dell'applicazione, si autentica con un'identità gestita in modo che non compaia alcun segreto nella stringa di connessione e abilita la crittografia Tabular Data Stream (TDS) 8.0 con validazione completa del certificato. Imposta un timeout per ogni tentativo di accesso e riprova i fallimenti transitori con retrocesso esponenziale e jitter.

Per brevità, lo snippet C++ in questo articolo omette le direttive include, l’allocazione degli handle e la funzione di supporto per la registrazione.

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 e ConnectRetryInterval abilitano la resilienza delle connessioni inattive, che ripristina automaticamente una connessione caduta durante l'inattività. Non riprovano il collegamento iniziale, motivo per cui questo frammento implementa anche il retry a livello di applicazione. Tieni entrambi.

ODBC fornisce informazioni diagnostiche tramite SQLGetDiagRec anziché tramite il solo codice di ritorno, quindi classifica gli errori prima di ritentare. Un errore di autenticazione o di configurazione provoca un fallimento immediato, anziché consumare l'intero limite di tentativi.

Per altre informazioni su ogni parte di questa configurazione, vedere:

• Parole chiave e attributi della stringa di connessione e DSN
• Usa Microsoft Entra ID con il driver ODBC
• Risoluzione dei problemi di crittografia della connessione
• Resilienza della connessione
• Disponibilità elevata e ripristino di emergenza

Per il catalogo degli errori transitori di Azure SQL, vedere codici di errore transitorio.

Funzionalità principali

• Multipiattaforma: La stessa API su Windows, Linux e macOS.
• Autenticazione Microsoft Entra ID: Connessioni senza password con identità gestita, service principal, flussi interattivi e integrati.
• Crittografia rigorosa: connessioni TDS 8.0 con validazione completa dei certificati nella versione 18 e successive.
• Always Encrypted: crittografia lato client per colonne sensibili, con supporto per provider di keystore personalizzati.
• Resilienza della connessione: Ripristino trasparente di una connessione che si è interrotta mentre era inattiva.
• Alta disponibilità: Supporto per listener del gruppo di disponibilità con MultiSubnetFailover.
• Classificazione dei dati: Metadati di sensibilità per colonne classificate.
• Tipo di dato vettoriale: Supporto nativo per il tipo vettoriale .
• Transazioni distribuite: supporto alle transazioni XA tramite il Microsoft Distributed Transaction Coordinator (MSDTC).
• Strumenti complementari: sqlcmd e bcp, installati separatamente.

Inizia subito

Installare il driver

Configurazione e connessione

Autenticazione e sicurezza

Disponibilità elevata e resilienza

Uso dei dati

Diagnosticare e risolvere i problemi

Note di rilascio e correzioni di bug

Reference

Contenuti correlati

• Riferimento del programmatore ODBC: La specifica API ODBC che questo driver implementa, documentata separatamente dal driver.
• Funzionalità del SQL Server Native Client: Comportamento del driver documentato solo nel contenuto del Native Client. Questi articoli si applicano al driver ODBC per SQL Server, tranne dove descrivono OLE DB.
• BCP Utility: L'utilità di copia in massa, installata separatamente dal driver.
• Utilità sqlcmd: Utilità per query da riga di comando, installata separatamente dal driver.
• Matrice di supporto alle funzionalità dei driver
• Blog sui driver di SQL Server