Driver JDBC Microsoft per SQL Server

Scaricare il driver JDBC

Il driver JDBC (Microsoft Java Database Connectivity) per SQL Server è un driver JDBC di tipo 4 (puro Java, comunica direttamente il protocollo TDS SQL Server, nessuna libreria nativa necessaria) che consente a Java qualsiasi applicazione o server applicazioni di connettersi a SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric. Implementa le API JDBC standard e funziona con i principali server applicazioni Java, tra cui IBM WebSphere e SAP NetWeaver.

Scegliere il punto di partenza

• Per configurare un ambiente di sviluppo Java ed eseguire la prima query, iniziare con il Passaggio 1: Configurare l'ambiente di sviluppo, Passaggio 2: Creare un database SQL e Passaggio 3: Modello di verifica per la connessione a SQL tramite Java.
• Per connettersi a Azure SQL con l'autenticazione senza password, iniziare con Connetti usando l'autenticazione Microsoft Entra e Compilazione dell'URL di connessione.
• Per aggiungere il driver a una build Maven, Gradle o altra, passare a Scarica Microsoft driver JDBC per SQL Server.
• Per rendere un'app esistente resiliente agli errori temporanei, passare a Resilienza della connessione e Logica di ripetizione dei tentativi configurabile.
• Per diagnosticare un problema di connessione o query, vedere Diagnosi dei problemi relativi al driver JDBC e Risoluzione dei problemi di connettività.

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, ad esempio Servizio app di Azure impostazioni dell'app, variabili di ambiente o un file di configurazione e imposta il resto delle proprietà di connessione a livello di codice. La configurazione combina Transport Layer Security (TLS), identità gestita, tentativi di connessione in caso di errori temporanei, ripristino rapido del gruppo di failover, un timeout di accesso più esteso per coprire un failover a freddo e una logica di ripetizione configurabile dei tentativi (CRL) per le istruzioni che incontrano la limitazione delle richieste in Azure SQL o un failover durante l'esecuzione della query.

Per una maggiore sicurezza e maggiore scalabilità orizzontale, mantenere le informazioni di connessione al di fuori del codice. Nell'ambiente di produzione archiviare le informazioni di connessione nel sistema di configurazione dell'applicazione e usare Azure Key Vault per i valori sensibili e le impostazioni di connessione gestite centralmente. Per altre informazioni, vedere Protezione delle stringhe di connessione.

I frammenti di codice Java in questo articolo omettono importazioni e wrapper di classe per brevità.

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
String serverName = System.getenv("SQL_SERVER_NAME");
String databaseName = System.getenv("SQL_DATABASE_NAME");
String port = System.getenv().getOrDefault("SQL_PORT", "1433");

if (serverName == null || databaseName == null) {
    throw new IllegalStateException(
            "Set SQL_SERVER_NAME and SQL_DATABASE_NAME in your application configuration.");
}

String url = "jdbc:sqlserver://" + serverName + ":" + port;

Properties props = new Properties();
props.setProperty("databaseName", databaseName);
props.setProperty("encrypt", "true");
props.setProperty("trustServerCertificate", "false");
props.setProperty("authentication", "ActiveDirectoryManagedIdentity");
props.setProperty("loginTimeout", "120");         // 90 is the minimum floor for this retry profile; 120 leaves practical failover margin
props.setProperty("connectRetryCount", "5");     // retry transient connection failures up to 5 times (default 1)
props.setProperty("connectRetryInterval", "15"); // 15 seconds between connection retries (default 10)
props.setProperty("multiSubnetFailover", "true"); // recommended for any Azure SQL HA listener
// props.setProperty("applicationIntent", "ReadOnly"); // uncomment to route to a readable secondary
// Retry deadlocks and lock timeouts, plus Azure SQL throttling and mid-query failover.
props.setProperty("retryExec", "1205,1222:3,5+5;40501,40613,40197,10928,10929,49918:4,5*2");

try (Connection conn = DriverManager.getConnection(url, props);
     Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT 1")) {
    while (rs.next()) {
        System.out.println(rs.getInt(1));
    }
}

Questo frammento di codice è ottimizzato per i gruppi di failover di database SQL di Azure e Istanza gestita di SQL di Azure.

Impostare multiSubnetFailover=true solo quando ci si connette a un listener di un gruppo di failover, a un listener di un gruppo di disponibilità o a un endpoint dell'istanza del cluster di failover. L'uso di questa proprietà sugli endpoint che non sono listener a disponibilità elevata può compromettere le prestazioni e non è supportato. Per altre informazioni, vedere Supporto dei driver JDBC per la disponibilità elevata e il ripristino di emergenza.

Il frammento di codice non imposta retryConn perché il driver ritenta già per impostazione predefinita i più comuni errori di connessione temporanei di Azure SQL (inclusi 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 e 10929), tramite connectRetryCount e connectRetryInterval. Per l'elenco completo, vedere Elenco degli errori di connessione temporanei predefiniti. Aggiungi retryConn con +<errorNumber> solo quando devi estendere l'elenco con un errore non ancora previsto, oppure impostalo su <errorNumber> (senza + iniziale) per sostituirlo. Se si inserisce lo stesso valore in un URL JDBC, eseguire il wrapping come retryConn={+<errorNumber>} o retryConn={<errorNumber>}.

La retryExec proprietà ha due parti, scritte come rule1;rule2 quando la si imposta a livello di codice. Se inserisci lo stesso valore in un URL JDBC, racchiudi ogni regola tra parentesi graffe come {rule1};{rule2}:

• {1205,1222:3,5+5} ritenta le vittime del deadlock (1205) e i timeout delle richieste di blocco (1222) tre volte con un backoff lineare di 5, 10 e 15 secondi. Per 1205, SQL Server esegue il rollback della transazione prima che il driver visualizzi l'errore, quindi la ripetizione di una singola istruzione è sicura. Se l'istruzione che ha causato il deadlock faceva parte di una transazione composta da più istruzioni, anche le istruzioni precedenti sono state annullate e CRL non le riesegue, quindi racchiudi l'intera transazione in un tuo ciclo di nuovi tentativi. 1222 lascia aperta la transazione e il retry a livello di istruzione riesegue solo l'istruzione all'interno della transazione originale; se devi anche limitare la durata della transazione, racchiudi l'intera transazione in un tuo ciclo di nuovi tentativi.

• {40501,40613,40197,10928,10929,49918:4,5*2} ritenta per quattro volte gli errori di limitazione di Azure SQL, il failover durante la query e gli errori dovuti ai limiti delle risorse, con un backoff esponenziale di 5, 10, 20 e 40 secondi. Questi errori si trovano nell'elenco temporaneo predefinito per il ciclo di connessione , ma retryExec è ciò che li intercetta quando generano una query intermedia su una connessione stabilita. I backoff CRL sono vincolati da queryTimeout. Se si imposta queryTimeout su un valore inferiore al prossimo tempo di attesa previsto, il driver interrompe anticipatamente l'attesa e rilancia l'eccezione. Scegliere un valore queryTimeout che sia almeno pari alla somma dei tempi di attesa CRL e del tempo di esecuzione dell'istruzione, oppure accettare che i backoff più lunghi non si attivino.

Per i gruppi di failover di database SQL di Azure, le repliche denominate di Hyperscale e il read scale-out oppure i listener del gruppo di disponibilità Always On, impostare applicationIntent=ReadOnly quando si desidera connettersi a una replica secondaria leggibile. Per i cloud sovrani in cui il Subject Alternative Name (SAN) del certificato non include l'host a cui ti stai connettendo, imposta anche hostNameInCertificate in modo che corrisponda (ad esempio, *.database.usgovcloudapi.net per Azure per enti pubblici).

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

• Costruzione dell'URL della connessione
• Impostare le proprietà di connessione
• Connettersi con l'autenticazione di Microsoft Entra
• Resilienza della connessione
• Logica di ripetizione dei tentativi configurabile
• Supporto del driver JDBC per il ripristino di emergenza a disponibilità elevata
• Informazioni sulle proprietà di timeout nel driver JDBC

Per il catalogo degli errori temporanei di Azure SQL, vedere Risolvere gli errori di connessione temporanei.

Funzionalità principali

• JDBC conforme agli standard: driver di tipo 4. La build di JRE 11+ implementa JDBC 4.2, oltre ai metodi di delimitazione delle richieste di JDBC 4.3 (beginRequest, endRequest) e agli helper di quotatura Statement. Le API di partizionamento orizzontale di JDBC 4.3 (setShardingKey, la createConnectionBuilder famiglia) generano SQLFeatureNotSupportedException. La build JRE 8 implementa JDBC 4.2. Per la suddivisione per versione e l'elenco completo dei metodi supportati e non supportati 4.3, vedere supporto per le specifiche di Java e JDBC.
• Supporto della piattaforma a livello di piattaforma: viene eseguito in qualsiasi piattaforma con una macchina virtuale Java (JVM) supportata, tra cui Windows, Linux e macOS.
• Crittografato per impostazione predefinita: connessioni con crittografia TLS con encrypt=true come impostazione predefinita per i driver correnti.
• Autenticazione di Microsoft Entra ID: connessioni senza password con identità gestita, entità servizio, autenticazione interattiva, autenticazione integrata, catena di credenziali predefinita e flussi di token di accesso.
• Kerberos: autenticazione integrata per Active Directory locale.
• NTLM: autenticazione challenge/response di Windows per scenari senza dominio o legacy.
• Always Encrypted: crittografia lato client per colonne sensibili, con enclave sicure facoltative per operazioni eseguite sul posto.
• Copia in blocco: inserimenti ad alta velocità effettiva con l'API SQLServerBulkCopy e prestazioni per l'inserimento in batch per executeBatch.
• Resilienza della connessione: tentativi di connessione predefiniti per gli errori temporanei, oltre alla logica di ripetizione dei tentativi configurabile esplicitamente per le istruzioni () e a un elenco di errori di connessione personalizzabile (retryExecretryConn).
• Supporto completo dei tipi di dati di SQL Server: datetimeoffset, sql_variant, JSON, tipi spaziali, vettoriali, parametri con valori di tabella e tipi definiti dall'utente.

Get started

Configurazione e connessione

Authenticate

Sicurezza

Uso dei dati

Tipi di dati

Transazioni e concorrenza

Prestazioni e affidabilità

Diagnosticare e risolvere i problemi

Attività correlate

Contenuto correlato

• Driver JDBC Microsoft per SQL Server su GitHub
• Driver JDBC Microsoft per SQL Server in Maven Central
• Note di rilascio per Microsoft JDBC Driver per SQL Server
• Altre informazioni sul driver JDBC
• Moduli di connessione per Microsoft SQL Database