Driver Microsoft JDBC untuk SQL Server

Unduh driver JDBC

Driver Microsoft Java Database Connectivity (JDBC) untuk SQL Server adalah driver JDBC Tipe 4 (Java murni, berbicara dengan protokol TDS SQL Server secara langsung, tidak diperlukan pustaka asli) yang memungkinkan aplikasi Java atau server aplikasi apa pun terhubung ke SQL Microsoft Database Engine di Azure SQL Database, database SQL di Fabric, Azure SQL Managed Instance, dan di semua versi dan edisi SQL Server yang didukung (termasuk Edisi Ekspres). Ini mengimplementasikan API JDBC standar dan bekerja dengan server aplikasi Java utama, termasuk IBM WebSphere dan SAP NetWeaver.

Pilih titik awal Anda

Garis besar produksi untuk Azure SQL

Gunakan cuplikan ini sebagai titik awal untuk koneksi Azure SQL berorientasi produksi. Ini memuat nama server dan nama database dari konfigurasi aplikasi, seperti pengaturan aplikasi Azure App Service, variabel lingkungan, atau file konfigurasi, dan mengatur properti koneksi lainnya secara terprogram. Konfigurasi ini menggabungkan Transport Layer Security (TLS), identitas terkelola, percobaan ulang koneksi saat terjadi kegagalan sementara, pemulihan grup failover yang cepat, batas waktu login yang lebih lama untuk mengakomodasi failover cold-start, dan logika percobaan ulang yang dapat dikonfigurasi (CRL) untuk pernyataan yang mengalami pembatasan laju di Azure SQL atau failover di tengah kueri.

Untuk keamanan yang lebih tinggi dan peluasan skala yang lebih mudah, simpan informasi koneksi di luar kode Anda. Dalam produksi, simpan informasi koneksi di sistem konfigurasi aplikasi Anda, dan gunakan Azure Key Vault untuk nilai sensitif dan pengaturan koneksi yang dikelola secara terpusat. Untuk informasi selengkapnya, lihat Mengamankan string koneksi.

Potongan kode Java dalam artikel ini tidak menyertakan pernyataan impor dan deklarasi kelas pembungkus demi keringkasan.

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

Cuplikan ini dioptimalkan untuk grup failover Azure SQL Database dan Azure SQL Managed Instance.

Atur multiSubnetFailover=true hanya saat Anda tersambung ke pendengar grup failover, pendengar grup ketersediaan, atau titik akhir instans kluster failover. Menggunakan properti ini pada endpoint yang bukan listener ketersediaan tinggi (HA) dapat menurunkan performa dan tidak didukung. Untuk informasi selengkapnya, lihat Dukungan driver JDBC untuk Ketersediaan Tinggi, pemulihan bencana.

Cuplikan kode tidak menetapkan retryConn karena driver sudah secara bawaan mencoba kembali saat terjadi galat koneksi sementara Azure SQL yang paling umum (termasuk 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928, dan 10929), yang dikendalikan oleh connectRetryCount dan connectRetryInterval. Untuk daftar lengkapnya, lihat Daftar kesalahan koneksi sementara bawaan. Tambahkan retryConn dengan +<errorNumber> hanya jika Anda perlu memperluas daftar dengan kesalahan yang belum tercakup, atau atur ke <errorNumber> (tanpa + di awal) untuk menggantinya. Jika Anda menempatkan nilai yang sama dalam URL JDBC, bungkus sebagai retryConn={+<errorNumber>} atau retryConn={<errorNumber>}.

Properti retryExec ini memiliki dua bagian, ditulis seperti rule1;rule2 ketika Anda mengaturnya secara terprogram. Jika Anda menempatkan nilai yang sama dalam URL JDBC, bungkus setiap aturan dalam kurung kurawal sebagai {rule1};{rule2}:

  • {1205,1222:3,5+5} mencoba ulang korban deadlock (1205) dan waktu tunggu permintaan kunci yang habis (1222) tiga kali dengan jeda linear selama 5, 10, dan 15 detik. Untuk 1205, SQL Server mengembalikan transaksi sebelum driver melihat kesalahan, sehingga menjalankan ulang satu pernyataan aman. Jika pernyataan yang mengalami deadlock merupakan bagian dari transaksi multistatement, pernyataan-pernyataan sebelumnya juga di-rollback dan CRL tidak menjalankannya kembali, jadi bungkus seluruh transaksi dalam loop retry Anda sendiri. 1222 membiarkan transaksi tetap terbuka dan mekanisme percobaan ulang pada tingkat pernyataan hanya menjalankan ulang pernyataan di dalam transaksi asli; jika Anda juga perlu membatasi durasi transaksi, bungkus seluruh transaksi dalam loop percobaan ulang Anda sendiri.

  • {40501,40613,40197,10928,10929,49918:4,5*2} mencoba kembali pembatasan pada Azure SQL, failover di tengah kueri, dan kesalahan akibat batas sumber daya hingga empat kali dengan backoff eksponensial selama 5, 10, 20, dan 40 detik. Kesalahan ini ada dalam daftar transien bawaan untuk loop connect, tetapi retryExec yang menangkapnya saat error tersebut terjadi di tengah kueri pada koneksi yang sudah terjalin. Backoff CRL dibatasi oleh queryTimeout. Jika Anda menetapkan queryTimeout lebih rendah daripada waktu tunggu berikutnya yang direncanakan, driver akan menyerah lebih awal dan melempar ulang. Pilih queryTimeout yang setidaknya sebesar total waktu tunggu CRL Anda ditambah waktu proses pernyataan, atau terimalah bahwa backoff terpanjang tidak akan dipicu.

Untuk grup failover Azure SQL Database, replika bernama Hyperscale dan read scale-out, atau listener grup ketersediaan Always On, setel applicationIntent=ReadOnly saat Anda ingin terhubung ke replika sekunder yang dapat dibaca. Untuk sovereign cloud yang Subject Alternative Name (SAN) sertifikatnya tidak menyertakan host yang Anda gunakan untuk terhubung, atur juga hostNameInCertificate agar sesuai (misalnya, *.database.usgovcloudapi.net untuk Azure Government).

Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:

Untuk katalog kesalahan sementara Azure SQL, lihat Memecahkan masalah kesalahan koneksi sementara.

Fitur utama

  • JDBC berbasis standar: Driver tipe 4. Build JRE 11+ mengimplementasikan JDBC 4.2 serta metode pembatas permintaan JDBC 4.3 (beginRequest, endRequest) dan fungsi bantu pengutipan Statement. API sharding JDBC 4.3 (setShardingKey, keluarga createConnectionBuilder) menghasilkan SQLFeatureNotSupportedException. Build JRE 8 mengimplementasikan JDBC 4.2. Untuk perincian per versi dan daftar lengkap metode 4.3 yang didukung dan tidak didukung, lihat dukungan spesifikasi Java dan JDBC.
  • Dukungan platform yang luas: Berjalan di platform apa pun dengan Java Virtual Machine (JVM) yang didukung, termasuk Windows, Linux, dan macOS.
  • Dienkripsi secara default: Koneksi terenkripsi TLS dengan encrypt=true sebagai default untuk driver saat ini.
  • autentikasi Microsoft Entra ID: Koneksi tanpa kata sandi dengan identitas terkelola, perwakilan layanan, interaktif, terintegrasi, rantai kredensial default, dan alur token akses.
  • Kerberos: Autentikasi terintegrasi untuk Active Directory lokal.
  • NTLM: autentikasi tantangan/respons Windows untuk skenario non-domain atau sistem lama.
  • Always Encrypted: Enkripsi sisi klien untuk kolom sensitif, dengan enklave aman opsional untuk operasi di tempat.
  • Salin massal: Penyisipan berthroughput tinggi dengan API SQLServerBulkCopy dan kinerja penyisipan batch untuk executeBatch.
  • Ketahanan koneksi: Percobaan ulang koneksi bawaan untuk kesalahan sementara, ditambah logika percobaan ulang opsional yang dapat dikonfigurasi untuk statemen (retryExec) dan daftar kesalahan koneksi yang dapat disesuaikan (retryConn).
  • Dukungan jenis data SQL Server yang kaya: datetimeoffset, sql_variant, JSON, spasial, vektor, parameter bernilai tabel, dan jenis yang ditentukan pengguna.

Get started

Article Deskripsi
Persyaratan sistem Versi Java, sistem operasi, dan SQL Server yang didukung.
Matriks dukungan Matriks kompatibilitas terperinci untuk rilis driver JDBC.
Unduh Microsoft JDBC Driver untuk SQL Server Tautan unduhan, koordinat Maven, dan artefak rilis.
Mulai menggunakan driver JDBC Instal driver, konfigurasikan lingkungan Anda, dan jalankan kueri pertama Anda.
Gambaran umum driver JDBC Arsitektur, fitur yang didukung, dan kepatuhan spesifikasi JDBC.

Mengonfigurasi dan menyambungkan

Article Deskripsi
Menyambungkan ke SQL Server dengan driver JDBC Buka koneksi ke instans SQL Server dari Java.
Menyambungkan ke database Azure SQL Sambungkan aplikasi Java ke Azure SQL Database.
Membangun URL koneksi Referensi lengkap mengenai sintaks dan properti URL jdbc:sqlserver://.
Mengatur properti koneksi Semua properti koneksi, default, dan cara mengaturnya.
Mengatur properti sumber data Konfigurasikan SQLServerDataSource untuk digunakan dengan JNDI dan server aplikasi.
Bekerja dengan koneksi Buka, gunakan kembali, dan tutup koneksi dengan benar.
Menggunakan pengumpulan koneksi Sumber data JNDI dan integrasi dengan kumpulan eksternal.
Ketahanan koneksi Percobaan ulang koneksi bawaan dan deteksi koneksi terputus.
Logika coba lagi yang dapat dikonfigurasi Coba lagi pernyataan yang gagal dengan retryExec dan sesuaikan daftar coba lagi koneksi dengan retryConn.
Memahami properti batas waktu di driver JDBC loginTimeout, queryTimeout, batas waktu soket, dan bagaimana mereka berinteraksi.
Menginstal driver JDBC Kemas dan sebarkan driver dengan aplikasi Anda.

Melakukan autentikasi

Article Deskripsi
Autentikasi Microsoft Entra Identitas terkelola, perwakilan layanan, interaktif, terintegrasi, dan autentikasi token akses.
Autentikasi terintegrasi Kerberos Sambungkan dengan Kerberos dan Direktori Aktif.
Autentikasi NTLM Gunakan kredensial NTLM untuk mengautentikasi.
Autentikasi sertifikat klien untuk skenario loopback Mengautentikasi klien dengan sertifikat pada koneksi loopback.

Secure

Article Deskripsi
Mengamankan aplikasi driver JDBC Panduan keamanan untuk aplikasi Java yang menggunakan driver.
Keamanan aplikasi Model ancaman dan rekomendasi mendalam pertahanan.
Mengamankan string koneksi Jauhkan kredensial dan string koneksi dari sumber.
Mengonfigurasi klien untuk enkripsi Akar kepercayaan, penyematan sertifikat, dan pengaturan TLS.
Menyambungkan dengan enkripsi Paksa encrypt=true dan validasikan sertifikat server.
Memahami dukungan enkripsi Bagaimana pengemudi menegosiasikan TLS dengan SQL Server.
Memvalidasi input pengguna Parameterisasi SQL dan hindari injeksi.
Mode FIPS Jalankan driver di lingkungan yang mematuhi FIPS.
Selalu Terenkripsi Mengonfigurasi enkripsi sisi klien untuk kolom sensitif.
Selalu Terenkripsi dengan enklave yang aman Aktifkan beragam operasi pada kolom terenkripsi.
Referensi Always Encrypted API Permukaan API untuk penyedia enkripsi kolom dan penyimpanan kunci.

Bekerja dengan data

Article Deskripsi
Bekerja dengan pernyataan dan tataan hasil Dasar-dasar Statement, PreparedStatement, dan kumpulan hasil.
Menggunakan pernyataan dengan driver JDBC Jalankan pernyataan berparameter dan tidak berparameter.
Menangani pernyataan kompleks Prosedur tersimpan, beberapa hasil, dan jumlah pembaruan.
Bekerja dengan kumpulan hasil Ulangi, perbarui, dan gulir melalui hasil kueri.
Menggunakan beberapa tataan hasil Tangani kueri yang mengembalikan lebih dari satu kumpulan hasil.
Memahami jenis kursor Kursor khusus terusan, dapat digulir, dan dapat diperbarui.
Menggunakan parameter bernilai tabel Teruskan TABLE parameter ke prosedur tersimpan.
Menggunakan salinan massal dengan driver JDBC Penyisipan berthroughput tinggi dengan SQLServerBulkCopy.
API salin massal untuk penyisipan massal Percepat executeBatch untuk beban kerja INSERT.
Melakukan operasi batch Penyisipan, pembaruan, dan penghapusan massal.

Jenis data

Article Deskripsi
Bekerja dengan tipe data Petakan jenis Java ke jenis SQL Server.
Memahami jenis data driver JDBC Sistem tipe driver dan pemetaan JDBC.
Konversi jenis data Konversi implisit dan eksplisit antara Java dan SQL Server.
Perbedaan jenis data Kasus tepi saat memetakan tipe melintasi batas.
Jenis data JSON Menyimpan dan mengkueri kolom JSON.
Jenis data spasial Gunakan geometri dan geografi dari Java.
Jenis data vektor Bekerja dengan tipe vektor SQL Server.
sql_variant Membaca dan menulis kolom sql_variant.
Jenis yang ditentukan pengguna Gunakan tipe yang ditentukan pengguna CLR dari Java.
Dukungan set karakter nasional Penanganan Unicode dan kolom nvarchar.
Fitur internasional Pertimbangan lokal, kolaborasi, dan globalisasi.

Transaksi dan konkurensi

Article Deskripsi
Melakukan transaksi commit, rollback, dan semantik penerapan otomatis.
Memahami transaksi Siklus hidup transaksi dan praktik terbaik.
Tingkat isolasi Rekam jepret, baca berkomitmen, dapat diserialisasikan, dan lainnya.
Kontrol konkurensi Strategi konkurensi yang optimis dan pesimis.
Penguncian baris Cara SQL Server mengambil dan melepaskan kunci baris.
Menggunakan savepoint Pengembalian parsial dalam transaksi.
Mengelola ukuran transaksi Sesuaikan cakupan transaksi untuk menghindari penguncian yang berlangsung lama.
Transaksi XA Penerapan dua fase dengan SQLServerXADataSource.

Performa dan keandalan

Article Deskripsi
Meningkatkan performa dan keandalan Pengindeksan, kueri, dan penyetelan pada tingkat driver.
Penyimpanan cache metadata statemen yang disiapkan Gunakan kembali rencana pernyataan yang disiapkan.
Performa parameter pernyataan yang disiapkan Penentuan tipe parameter dan penggunaan ulang rencana eksekusi.
Penyanggaan adaptif Alirkan kolom berukuran besar tanpa memuatnya sepenuhnya ke dalam memori.
Menutup objek saat tidak digunakan Segera bebaskan sumber daya Statement, ResultSet, dan Connection.
Ketersediaan tinggi dan pemulihan bencana Pendengar grup ketersediaan dan failover multi-subnet.
Pencerminan database Gunakan driver dengan mitra pencerminan basis data.

Mendiagnosis dan memecahkan masalah

Article Deskripsi
Mendiagnosis masalah dengan driver JDBC Pelacakan, pencatatan log, dan mode kegagalan yang umum.
Pemecahan masalah konektivitas Kesalahan koneksi, kegagalan jabat tangan TLS, dan instans bernama.
Penelusuran operasi driver Aktifkan pengelogan JDK untuk driver.
Pencatat performa dan panggilan balik Mencatat metrik kinerja untuk setiap pernyataan.
Log peristiwa yang diperluas Korelasikan kesalahan klien dengan Extended Events di sisi server.
Menangani kesalahan SQLException, kode kesalahan, dan petunjuk coba lagi.
Article Deskripsi
Catatan rilis Riwayat versi dan apa yang baru di setiap rilis.
Ketergantungan fitur Dependensi opsional untuk Entra ID, Kerberos, Always Encrypted, dan lainnya.
Kepatuhan JDBC 4.3 Kesuaian API JDBC 4.3.
Kepatuhan JDBC 4.2 Kesuaian API JDBC 4.2.
Kepatuhan JDBC 4.1 Kesuaian API JDBC 4.1.
Kepatuhan dan hukum Kepatuhan terhadap spesifikasi dan lisensi.
Referensi API driver JDBC Kelas, antarmuka, metode, dan bidang yang diekspos oleh driver.
Contoh aplikasi driver JDBC Contoh kode end-to-end.
FAQ Tanya jawab umum.

Konten terkait

  • Last updated on