Ovladač Microsoft JDBC pro SQL Server

Stáhnout ovladač JDBC

Ovladač Microsoft Java Database Connectivity (JDBC) pro SQL Server je JDBC ovladač typu 4 (čistý Java, komunikuje přímo s protokolem SQL Server TDS, není potřeba nativní knihovna), který umožňuje jakékoli Java aplikaci nebo aplikačnímu serveru připojit se k Microsoft SQL Database Engine v Azure SQL Database, SQL database ve Fabric, Azure SQL Managed Instance a ve všech podporovaných verzích a edicích SQL Server (včetně Express Editions). Implementuje standardní rozhraní API JDBC a pracuje s hlavními aplikačními servery Java, včetně IBM WebSphere a SAP NetWeaver.

Výběr výchozího bodu

• Pokud chcete nastavit vývojové prostředí Java a spustit první dotaz, začněte krokem 1: Konfigurace vývojového prostředí, krok 2: Vytvoření databáze SQL a krok 3: Testování konceptu připojení k SQL pomocí Java.
• Pokud se chcete připojit k Azure SQL s ověřováním bez hesla, začněte připojením pomocí ověřování Microsoft Entra a vytvořením adresy URL připojení.
• Pokud chcete přidat ovladač do sestavení Maven, Gradle nebo jiného nástroje pro sestavení, přejděte na Stažení ovladače Microsoft JDBC Driver pro SQL Server.
• Pokud chcete, aby existující aplikace byla odolná vůči přechodným selháním, přejděte do odolnosti připojení a konfigurovatelné logiky opakování.
• Pokud chcete diagnostikovat potíže s připojením nebo dotazem, přejděte do části Diagnostika problémů s ovladačem JDBC a řešením potíží s připojením.

Směrný plán výroby pro Azure SQL

Tento fragment kódu použijte jako výchozí bod pro produkční Azure SQL připojení. Načte název serveru a název databáze z konfigurace aplikace, jako je Azure App Service nastavení aplikace, proměnné prostředí nebo konfigurační soubor, a nastaví zbytek vlastností připojení programově. Konfigurace zahrnuje protokol TLS (Transport Layer Security), spravovanou identitu, opakování připojení při přechodných selháních, rychlé obnavení skupiny převzetí služeb při selhání, delší časový limit přihlášení, který pokrývá převzetí služeb při selhání po studeném spuštění, a konfigurovatelnou logiku opakování (CRL) pro příkazy, které narazí na omezení Azure SQL nebo na převzetí služeb při selhání uprostřed dotazu.

Kvůli vyššímu zabezpečení a snadnějšímu horizontálnímu navýšení kapacity zachovejte informace o připojení mimo váš kód. V produkčním prostředí uložte informace o připojení do konfiguračního systému aplikace a použijte Azure Key Vault pro citlivé hodnoty a nastavení centrálně spravovaného připojení. Další informace naleznete v tématu Zabezpečení připojovacích řetězců.

Ukázky kódu v jazyce Java v tomto článku kvůli stručnosti vynechávají importy a obalující deklarace tříd.

// 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));
    }
}

Tato ukázka kódu je přizpůsobena pro skupiny převzetí služeb při selhání ve službě Azure SQL Database a pro Azure SQL Managed Instance.

Nastavte multiSubnetFailover=true pouze tehdy, když se připojujete k listeneru skupiny převzetí služeb při selhání, listeneru skupiny dostupnosti nebo ke koncovému bodu instance clusteru s podporou převzetí služeb při selhání. Použití této vlastnosti u koncových bodů, které nejsou posluchači vysoké dostupnosti (HA), může snížit výkon a není podporováno. Další informace najdete v tématu Podpora ovladačů JDBC pro vysokou dostupnost, zotavení po havárii.

Tato ukázka kódu nenastavuje retryConn, protože ovladač už ve výchozím nastavení automaticky opakuje pokusy při nejběžnějších přechodných chybách připojení k Azure SQL (včetně chyb 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 a 10929), což je řízeno parametry connectRetryCount a connectRetryInterval. Úplný seznam najdete v tématu Předdefinovaný seznam chyb přechodných připojení. Přidejte retryConn s +<errorNumber> jen tehdy, když potřebujete rozšířit seznam o chybu, kterou dosud nepokrývá, nebo ji nastavte na <errorNumber> (bez úvodního +) a tím ji nahraďte. Pokud umístíte stejnou hodnotu do adresy URL JDBC, zabalte ji jako retryConn={+<errorNumber>} nebo retryConn={<errorNumber>}.

Vlastnost retryExec má dvě části, napsané jako rule1;rule2 při programovém nastavení. Pokud umístíte stejnou hodnotu do adresy URL JDBC, zabalte každé pravidlo do složených závorek jako {rule1};{rule2}:

• {1205,1222:3,5+5} třikrát opakuje pokus u transakcí ukončených kvůli vzájemnému zablokování (1205) a při vypršení časového limitu žádosti o uzamčení (1222), s lineárně rostoucí prodlevou 5, 10 a 15 sekund. U chyby 1205 SQL Server vrátí transakci zpět dříve, než ovladač chybu zaznamená, takže je bezpečné znovu spustit jeden příkaz. Pokud byl příkaz, který se stal obětí deadlocku, součástí transakce obsahující více příkazů, byly vráceny zpět i dřívější příkazy a CRL je znovu nespouští, proto celou transakci obalte do vlastního cyklu opakování. 1222 ponechá transakci otevřenou a opakování na úrovni příkazu znovu provede pouze příkaz uvnitř původní transakce; pokud také potřebujete omezit dobu trvání transakce, obalte celou transakci do vlastního cyklu opakování.

• {40501,40613,40197,10928,10929,49918:4,5*2} čtyřikrát zopakuje pokus po omezení propustnosti ve službě Azure SQL, převzetí služeb při selhání během provádění dotazu a chybách způsobených limitem prostředků s exponenciálně rostoucí prodlevou 5, 10, 20 a 40 sekund. Tyto chyby jsou ve vestavěném seznamu přechodných chyb pro smyčku connect, ale retryExec je zachytí, když k nim dojde uprostřed dotazu nad již navázaným připojením. Prodlevy CRL jsou omezeny hodnotou queryTimeout. Pokud nastavíte queryTimeout na nižší hodnotu, než je další plánovaná čekací doba, ovladač to předčasně vzdá a výjimku znovu vyvolá. Zvolte queryTimeout, který je alespoň tak velký jako součet vašich čekacích dob CRL a doby běhu příkazu, nebo se smiřte s tím, že se nejdelší backoffy nespustí.

U skupin pro převzetí služeb při selhání Azure SQL Database, pojmenovaných replik Hyperscale a škálování čtení nebo naslouchačů skupin dostupnosti Always On nastavte applicationIntent=ReadOnly, pokud chcete směrovat na čitelnou sekundární repliku. V suverénních cloudech, kde alternativní název subjektu certifikátu (SAN) neobsahuje hostitele, ke kterému se připojujete, nastavte také hostNameInCertificate tak, aby odpovídal (například *.database.usgovcloudapi.net pro Azure Government).

Další informace o jednotlivých částech této konfigurace najdete tady:

• Sestavení adresy URL připojení
• Nastavení vlastností připojení
• Připojte se pomocí ověřování Microsoft Entra
• Odolnost připojení
• Konfigurovatelná logika opakování
• Podpora ovladačů JDBC pro vysokou dostupnost, zotavení po havárii
• Pochopení vlastností časových limitů v ovladači JDBC

Katalog Azure SQL přechodných chyb naleznete v tématu Řešení přechodných chyb připojení.

Klíčové funkce

• JDBC založené na standardech: Ovladač typu 4. Sestavení JRE 11+ implementuje JDBC 4.2 a navíc metody JDBC 4.3 pro vymezení hranic požadavků (beginRequest, endRequest) a pomocné funkce Statement pro uvozování. Rozhraní API JDBC 4.3 pro shardování (setShardingKey, rodina createConnectionBuilder) vyvolávají SQLFeatureNotSupportedException. Sestavení JRE 8 implementuje JDBC 4.2. Rozpis jednotlivých verzí a úplný seznam podporovaných a nepodporovaných metod 4.3 najdete v tématu Java a podpora specifikace JDBC.
• Široká podpora platformy: Běží na libovolné platformě s podporovaným Java virtuálním počítačem (JVM), včetně Windows, Linuxu a macOS.
• Šifrované ve výchozím nastavení: Připojení šifrovaná protokolem encrypt=true TLS jako výchozí pro aktuální ovladače.
• ověřování Microsoft Entra ID: připojení bez hesla se spravovanou identitou, instančním objektem, interaktivním, integrovaným, výchozím řetězem přihlašovacích údajů a toky přístupového tokenu.
• Kerberos: Integrované ověřování pro místní Active Directory.
• NTLM: Ověřování typu challenge-response systému Windows pro prostředí bez domény nebo starší scénáře.
• Always Encrypted: Šifrování na straně klienta pro citlivé sloupce s volitelnými zabezpečenými enklávy pro místní operace.
• Hromadné kopírování: vysoce propustné vkládání pomocí rozhraní API SQLServerBulkCopy a vysoký výkon dávkového vkládání pro executeBatch.
• Odolnost připojení: Vestavěné opakované pokusy o připojení při přechodných chybách a volitelně konfigurovatelná logika opakování pro příkazy (retryExec) a přizpůsobitelný seznam chyb připojení (retryConn).
• Podpora bohatých datových typů SQL Server: datetimeoffset, sql_variant, JSON, spatial, vector, parametry hodnot tabulky a uživatelem definované typy.

Začínáme

Article	Description
Systémové požadavky	Podporované verze Java, operačního systému a SQL Server.
Matice podpory	Podrobná matice kompatibility pro vydání ovladačů JDBC
Stažení ovladače Microsoft JDBC pro SQL Server	Odkazy ke stažení, souřadnice Mavenu a artefakty vydání.
Začínáme s ovladačem JDBC	Nainstalujte ovladač, nakonfigurujte prostředí a spusťte první dotaz.
Přehled ovladače JDBC	Architektura, podporované funkce a dodržování předpisů specifikace JDBC

Konfigurace a připojení

Article	Description
připojení k SQL Serveru pomocí ovladače JDBC	Otevřete připojení k instanci SQL Server z Java.
Připojení k databázi Azure SQL	Připojte aplikaci Java k Azure SQL Database.
Sestavení adresy URL připojení	Úplný přehled syntaxe a vlastností adresy URL jdbc:sqlserver://.
Nastavení vlastností připojení	Všechny vlastnosti připojení, výchozí hodnoty a způsob jejich nastavení
Nastavení vlastností zdroje dat	Nakonfigurujte SQLServerDataSource pro použití s JNDI a aplikačními servery.
Práce s připojením	Správně otevřete, znovu použijte a ukončete připojení.
Použití sdružování připojení	Zdroje dat JNDI a integrace s externími fondy
Odolnost připojení	Integrované opakování připojení a detekce přerušeného připojení
Konfigurovatelná logika opakování	Opakovat nezdařené příkazy pomocí retryExec a přizpůsobit seznam opakování připojení pomocí retryConn.
Pochopení vlastností časových limitů v ovladači JDBC	loginTimeout, queryTimeout, časové limity socketů a jejich vzájemné působení.
Nasazení ovladače JDBC	Zabalte ovladač do aplikace a nasaďte ho.

Autentizovat

Article	Description
Ověřování Microsoft Entra	Spravovaná identita, instanční objekt služby, interaktivní ověřování, integrované ověřování a ověřování pomocí přístupového tokenu.
Integrované ověřování Kerberos	Připojte se pomocí protokolu Kerberos a služba Active Directory.
Ověřování NTLM	K ověření použijte přihlašovací údaje NTLM.
Ověřování klientských certifikátů pro scénáře zpětné smyčky	Ověřování klientů pomocí certifikátů přes připojení zpětné smyčky.

Bezpečný

Article	Description
Zabezpečení aplikací ovladačů JDBC	Pokyny k zabezpečení pro Java aplikace, které používají ovladač.
Zabezpečení aplikací	Doporučení k modelu hrozeb a hloubkové obraně
Zabezpečení připojovacích řetězců	Uchovávejte přihlašovací údaje a připojovací řetězce mimo zdroj.
Konfigurace klienta pro šifrování	Důvěřovat kořenovým certifikátům, připnutí certifikátu a nastavení protokolu TLS
Připojení pomocí šifrování	Vynuťte encrypt=true a ověřte certifikát serveru.
Principy podpory šifrování	Jak ovladač vyjedná protokol TLS s SQL Server
Ověřování vstupu uživatele	Parametrizovat SQL a vyhnout se injektáži.
FIPS režimu	Spusťte ovladač v prostředích kompatibilních se standardem FIPS.
Vždy šifrované	Nakonfigurujte šifrování na straně klienta pro citlivé sloupce.
Always Encrypted s využitím zabezpečených enkláv	Povolte pokročilé operace u šifrovaných sloupců.
Referenční informace k rozhraní API Always Encrypted	Plocha rozhraní API pro zprostředkovatele šifrování sloupců a úložiště klíčů

Práce s daty

Article	Description
Práce s příkazy a sadami výsledků	Základy Statement, PreparedStatement a sad výsledků.
Použití příkazů s ovladačem JDBC	Spusťte parametrizované a neparametrizované příkazy.
Zpracování složitých příkazů	Uložené procedury, více výsledků a počet aktualizací.
Práce se sadami výsledků	Iterujte, aktualizujte a procházejte výsledky dotazu.
Použití více sad výsledků	Zpracování dotazů, které vracejí více než jednu sadu výsledků
Pochopení typů kurzorů	Kurzory pouze vpřed, posuvné a aktualizovatelné.
Použití tabulkových parametrů	Předejte TABLE parametry uloženým procedurům.
Použití hromadného kopírování s ovladačem JDBC	Vkládání s vysokou propustností pomocí SQLServerBulkCopy.
API pro hromadné kopírování pro dávkové vkládání	Urychlete executeBatch pro úlohy INSERT.
Provádění dávkových operací	Dávkové vkládání, aktualizace a mazání.

Datové typy

Article	Description
Práce s datovými typy	Mapování Java typů na typy SQL Server
Porozumění datovým typům ovladačů JDBC	Systém typů ovladačů a mapování JDBC.
Převody datových typů	Implicitní a explicitní převody mezi Java a SQL Server
Rozdíly mezi datovými typy	Okrajové případy při mapování typů přes hranici.
Datový typ JSON	Ukládání a dotazování sloupců JSON
Prostorové datové typy	Použijte geometrii a zeměpisnou oblast z Java.
Vektorový datový typ	Práce s typem SQL Server vector
sql_variant	Čtení a zápis sql_variant sloupců
Uživatelem definované typy	Používejte uživatelem definované typy CLR z Java.
Podpora národní znakové sady	Zpracování kódování Unicode a sloupce typu nvarchar.
Mezinárodní funkce	Národní prostředí, řazení a aspekty globalizace.

Transakce a souběžnost

Article	Description
Provádění transakcí	commit, rollback a sémantiku automatického potvrzování.
Vysvětlení transakcí	Životní cyklus transakcí a osvědčené postupy
Úrovně izolace	Snímek, čtení potvrzené, serializovatelné a další.
Řízení souběžnosti	Optimistické a pesimistické strategie souběžnosti.
Uzamykání řádků	Jak SQL Server vezme a uvolní zámky řádků.
Použití savepointů	Částečné vrácení v rámci transakce.
Správa velikosti transakcí	Vylaďte obor transakcí, abyste se vyhnuli dlouhotrvajícím zámkům.
Transakce XA	Dvoufázové potvrzení transakce s SQLServerXADataSource.

Výkon a spolehlivost

Article	Description
Zvýšení výkonu a spolehlivosti	Ladění na úrovni indexu, dotazu a ovladače.
Ukládání metadat připravených příkazů do mezipaměti	Opakovaně používejte připravené plány výpisů.
Výkon parametrů připravených příkazů	Typování parametrů a opakované použití plánu spuštění
Adaptivní vyrovnávací paměť	Streamovat velké sloupce bez jejich úplné načtení do paměti.
Zavření objektů, pokud se nepoužívají	Okamžitě uvolněte Statement, ResultSet a Connection prostředky.
Vysoká dostupnost a zotavení po havárii	Naslouchací procesy skupin dostupnosti a převzetí služeb při selhání ve více podsítích
Zrcadlení databáze	Použijte ovladač s partnery pro zrcadlení databáze.

Diagnostika a řešení potíží

Article	Description
Diagnostika problémů s ovladačem JDBC	Trasování, protokolování a běžné způsoby selhání.
Řešení potíží s připojením	Chyby připojení, selhání metody handshake protokolu TLS a pojmenované instance
Trasování provozu ovladače	Povolte protokolování sady JDK pro ovladač.
Záznamník výkonu a zpětné volání	Zachytávání metrik výkonu jednotlivých příkazů
Protokol rozšířených událostí	Korelujte chyby klienta s rozšířenými událostmi na straně serveru.
Zpracování chyb	SQLException, kódy chyb a rady pro opakování.

Související úkoly

Article	Description
Poznámky k vydání	Historie verzí a novinky v jednotlivých verzích
Závislosti funkcí	Volitelné závislosti pro Entra ID, Kerberos, Always Encrypted a další.
Dodržování předpisů JDBC 4.3	Shoda rozhraní API JDBC 4.3
Dodržování předpisů JDBC 4.2	Shoda rozhraní API JDBC 4.2
Dodržování předpisů JDBC 4.1	Shoda rozhraní API JDBC 4.1
Dodržování předpisů a právní předpisy	Soulad se specifikací a licencování.
Referenční informace k rozhraní API ovladače JDBC	Třídy, rozhraní, metody a pole vystavená ovladačem
Ukázkové aplikace ovladačů JDBC	Kompletní ukázky kódu
Nejčastější dotazy	Nejčastější dotazy

Související obsah

• ovladač Microsoft JDBC pro SQL Server na GitHub
• ovladač Microsoft JDBC pro SQL Server v Centru Mavenu
• Poznámky k verzi pro ovladač Microsoft JDBC pro SQL Server
• Vyhledání dalších informací o ovladači JDBC
• Moduly připojení pro Microsoft SQL databáze