Szybki start: Połącz się z SQL Server za pomocą Java i Maven

Użyj sterownika Microsoft JDBC Driver for SQL Server, aby połączyć aplikację Java z SQL Server, usługą Azure SQL Database lub bazą danych SQL w usłudze Fabric. Ten szybki start wykorzystuje Maven do pobierania zależności, odczytuje ustawienia połączenia ze zmiennych środowiskowych oraz weryfikuje parametryzowany wynik zapytania. Nie potrzebujesz AdventureWorks ani żadnych przykładowych tabel.

W przypadku usługi Azure SQL Database lub bazy danych SQL w usłudze Fabric używaj uwierzytelniania Microsoft Entra ID bez przechowywania hasła w swojej aplikacji. Podczas pracy w środowisku lokalnym zaloguj się za pomocą przeglądarki. Dla aplikacji hostowanej w Azure użyj tożsamości zarządzanej.

Wymagania wstępne

• Java Development Kit (JDK) 21. Sprawdź swoją instalację za pomocą java -version.
• Apache Maven. Uruchom mvn -version i sprawdź, że Maven używa JDK 21.
• Baza danych i uprawnienia do połączenia się z nią. Wybierz hostowaną bazę danych lub kontener SQL Server w Wybierz swoją bazę danych. Zapytanie odczytuje obliczoną wartość i nie tworzy ani nie modyfikuje obiektów bazy danych.
• Dostęp sieciowy do punktu końcowego bazy danych. Dla Azure SQL, konfiguruj dostęp do sieci. W przypadku usługi Fabric postępuj zgodnie z instrukcjami w artykule Połącz z bazą danych SQL. W przypadku SQL Server włącz Transmission Control Protocol/Internet Protocol (TCP/IP) i użyj skonfigurowanego portu.
• Certyfikat serwera, któremu ufasz w środowisku uruchomieniowym Java. Aplikacja wymaga szyfrowania i weryfikuje certyfikat serwera. Jeśli chodzi o prywatny organ certyfikacji, wybierz Zaufaj prywatnemu organowi certyfikacji.

Wybierz swoją bazę danych

Użyj istniejącej bazy danych lub stwórz ją, korzystając z poniższych wskazówek. Pusta baza danych wystarczy.

Obrazy kontenerów systemu Linux dla programu SQL Server wymagają obsługiwanego hosta x86-64. Na komputerze deweloperskim ARM64 uruchom tę aplikację Java na hostowanej bazie danych lub kontenerze na obsługiwanym hostze zdalnym, zamiast polegać na emulacji kontenerów.

Nowy kontener może używać certyfikatu, któremu JDK nie ufa. Przed uruchomieniem tego przykładu skonfiguruj certyfikat serwera, a dla prywatnego emitenta skonfiguruj magazyn zaufania Java. Warto też mieć włączoną walidację certyfikatów dla połączeń kontenerowych.

Stwórz projekt Maven

Utwórz katalog o nazwie jdbc-quickstart. W tym katalogu stwórz pom.xml z następującą zawartością. Maven zarządza ścieżką klasy; nie musisz ręcznie pobierać plików Java archive (JAR).

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>jdbc-quickstart</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
            <version>13.6.0.jre11</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-core-http-netty</artifactId>
            <version>1.16.6</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.18.4</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.14.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <executable>${java.home}/bin/java</executable>
                    <arguments>
                        <argument>-classpath</argument>
                        <classpath />
                        <argument>Quickstart</argument>
                    </arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Artefakt sterownika jre11 działa z JDK 21. Jawna azure-identity zależność dostarcza biblioteki uwierzytelniania potrzebne dla trybów Microsoft Entra w tym szybkim starcie; te biblioteki są opcjonalnymi zależnościami sterownika i nie są automatycznie dodawane do aplikacji.

Wersje te odpowiadają opublikowanemu JDBC 13.6.0 Maven project object model (POM). Jawna azure-core-http-netty zależność zachowuje wersję transportową wybraną przez dane wydanie sterownika.

Aby zobaczyć aktualizacje sterowników, sprawdź stronę pobierania, opublikowane wersje Maven oraz matrycę wsparcia Java. Gdy aktualizujesz sterownik, dopasuj zależności uwierzytelniania do opublikowanego POM sterownika. Zobacz Zależności cech. Używaj wersji jawnych zamiast zakresów wersji Maven lub LATEST.

Konfiguruj połączenie

Ustaw zmienne środowiskowe w tym samym terminalu, w którym uruchamiasz Maven. Zamień <server> i <database> z nazwą punktu końcowego i bazy danych. Ustaw SQL_SERVER_NAME tylko nazwę hosta, bez URL-a JDBC czy portu.

Jeśli skopiowana wartość serwera to tcp:<server>,1433, używaj tylko <server> dla SQL_SERVER_NAME i ustaw SQL_PORT na 1433. Nie dodawaj przedrostka tcp: ani przyrostka ,1433 w nazwie hosta.

Azure SQL lub Fabric z uwierzytelnianiem Microsoft Entra

Do rozwoju lokalnego użyj ActiveDirectoryInteractive. Sterownik otwiera przeglądarkę do logowania i obsługuje uwierzytelnianie wieloskładnikowe. Zaloguj się jako osoba mająca dostęp do Twojej bazy danych. Nie ustawiaj SQL_USER ani SQL_PASSWORD dla tego trybu.

W przypadku usługi Azure SQL Database zastąp <server> pełną nazwą hosta, taką jak contoso.database.windows.net. Dla Fabric skopiuj nazwę hosta z ustawień połączenia bazy SQL; nie buduj jej z nazwy bazy ani nie dodawaj sufiksu Azure SQL. Fabric wymaga uwierzytelniania Microsoft Entra; nie używaj przykładu uwierzytelniania SQL dla Fabric.

$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "ActiveDirectoryInteractive"

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="ActiveDirectoryInteractive"

Dla aplikacji bezobsługowej hostowanej w zasobie platformy Azure z tożsamością zarządzaną przypisaną przez system:

1. Włącz zarządzaną tożsamość zasobu.
2. Poproś administratora o przyznanie tej tożsamości dostępu do bazy danych. Dla Azure SQL utwórz użytkownika bazy danych dla tożsamości. W przypadku Fabric należy przestrzegać wymagań uwierzytelniania i dostępu Fabric, w tym odpowiednich ustawień tenantów dla principalów usług.
3. Ustaw SQL_AUTHENTICATION na ActiveDirectoryManagedIdentity w konfiguracji aplikacji hosta. Zachowaj serwer, bazę danych i ustawienia portu. Ta sama aplikacja Java działa bez przeglądarki i hasła.

Zarządzana tożsamość wymaga obsługiwanego hosta Azure; nie zastępuje interaktywnego logowania na twojej stacji roboczej. Informacje na temat tożsamości przypisanych przez użytkownika i innych trybów uwierzytelniania można znaleźć w artykule Connect using Microsoft Entra authentication.

SQL Server z uwierzytelnianiem SQL

Dla kontenera SQL Server lub istniejącej instancji skonfigurowanej pod uwierzytelnianie SQL, ustaw SQL_AUTHENTICATIONSqlPassword i podaj logowanie SQL z dostępem do bazy danych. Nie używaj konta administratora serwera do tego przykładu. Monit hasła programu PowerShell wymaga programu PowerShell 7.1 lub nowszego.

$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "SqlPassword"
$env:SQL_USER = "<user_id>"
$env:SQL_PASSWORD = Read-Host "SQL password" -MaskInput

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
read -r -s -p "SQL password: " SQL_PASSWORD
printf '\n'
export SQL_PASSWORD

Użyj portu TCP swojej instancji, jeśli nie jest on 1433. Zmienne środowiskowe pozwalają trzymać poświadczenia poza kodem źródłowym, ale nie są magazynem sekretów. Nie zapisuj ich w logach ani nie zatwierdzaj ich w systemie kontroli wersji. Nie włączaj rejestrowania debugowania Mavena (-X), gdy ustawione są zmienne haseł: wtyczka wykonywania rejestruje wartości zmiennych środowiskowych procesu potomnego. W przypadku aplikacji wdrożonych korzystaj z ustawień zarządzania tajemnicami i bezpiecznego połączenia na swojej platformie.

Zaufaj prywatnemu organowi certyfikacji

Pomiń ten fragment, jeśli Twój JDK już ufa wydawcy certyfikatu serwera. W przeciwnym razie uzyskaj od administratora, za pośrednictwem zaufanego kanału, publiczny certyfikat i odcisk cyfrowy SHA-256 urzędu certyfikacji (CA), który wydał certyfikat. Nie ufaj certyfikatowi tylko dlatego, że serwer go przedstawił podczas nieudanych połączenia.

Ustaw SQL_SERVER_NAME nazwę DNS objętą certyfikatem serwera i rozwiązywalną z komputera. Aplikacja nie nadpisuje hostNameInCertificate, więc sterownik weryfikuje skonfigurowaną nazwę serwera. Dodanie zaufanego CA nie naprawia niezgodności między nazwami certyfikatów.

Użyj keytool z tej samej instalacji JDK 21, której używa Maven. Zamień <ca-certificate-file> na ścieżkę do zweryfikowanego certyfikatu CA, <jdk-home> na katalog tego JDK, a <trust-store-file> na nową ścieżkę bezwzględną poza projektem. Przechowuj magazyn zaufanych certyfikatów w katalogu, którego inni nieuprzywilejowani użytkownicy nie mogą modyfikować. Zatrzymaj się, jeśli jakieś polecenie nie zadziała.

1. Sprawdź certyfikat CA i porównaj jego odcisk palca SHA-256 z wartością podaną przez administratora.

   keytool -printcert -file "<ca-certificate-file>"
   

2. Stwórz dedykowany magazyn zaufania PKCS12, kopiując publiczne korzenie JDK. Nie modyfikuj pliku cacerts zainstalowanego pakietu JDK ani nie nadpisuj istniejącego magazynu certyfikatów zaufania.

   keytool -importkeystore -srckeystore "<jdk-home>/lib/security/cacerts" -destkeystore "<trust-store-file>" -deststoretype PKCS12
   

   Wprowadź nowe hasło sklepu docelowego zgodnie z monitami. Do hasła do przechowywania kodu użyj wartości podanej przez dostawcę lub administratora JDK. Kopiowanie publicznych korzeni utrzymuje zaufanie serwerom korzystającym z publicznych CA.

3. Dodaj zweryfikowanego CA do dedykowanego sklepu.

   keytool -importcert -alias sql-server-ca -file "<ca-certificate-file>" -keystore "<trust-store-file>" -storetype PKCS12
   

   Wprowadź hasło do sklepu docelowego. Przed potwierdzeniem importu sprawdź, czy wyświetlany odcisk palca odpowiada wartości zweryfikowanej.

Ustaw te dwie opcjonalne zmienne w terminalu, na którym uruchamiasz Maven. Użyj hasła do sklepu docelowego, które właśnie stworzyłeś. Monit hasła programu PowerShell wymaga programu PowerShell 7.1 lub nowszego.

$env:SQL_TRUST_STORE = "<trust-store-file>"
$env:SQL_TRUST_STORE_PASSWORD = Read-Host "Trust-store password" -MaskInput

export SQL_TRUST_STORE="<trust-store-file>"
read -r -s -p "Trust-store password: " SQL_TRUST_STORE_PASSWORD
printf '\n'
export SQL_TRUST_STORE_PASSWORD

Aplikacja Java odczytuje te zmienne i konfiguruje swój magazyn zaufania JDBC w sposób jawny. Pomiń obie zmienne, aby użyć domyślnej konfiguracji zaufania maszyny wirtualnej Java (JVM). Zachowaj trustServerCertificate=false i encrypt=true.

Maven uruchamia osobny proces Java dla tej aplikacji. Ustawienie właściwości Java Secure Socket Extension (JSSE), takiej jak javax.net.ssl.trustStore, za pomocą mvn -D... lub MAVEN_OPTS, nie powoduje skonfigurowania tego procesu potomnego. JAVA_TOOL_OPTIONS i JDK_JAVA_OPTIONS dochodzą do tego, ale JVM wypisuje te opcje podczas uruchamiania. Nie wpisuj haseł w żadnej z tych zmiennych. Zamiast tego użyj zmiennych aplikacyjnych z tej sekcji. Więcej informacji o konfiguracji zaufania znajdziesz w artykule Konfiguruj klienta do szyfrowania.

Dodaj aplikację Java

Z katalogu jdbc-quickstart utworz katalog źródłowy Java.

New-Item -ItemType Directory -Path src\main\java -Force | Out-Null

mkdir -p src/main/java

Zapisz następującą kompletną aplikację jako Quickstart.java w src/main/java.

Zapytanie SELECT CAST(? AS int) + 1 AS answer Transact-SQL (T-SQL) akceptuje jeden parametr. setInt wiąże wartość 41 oddzielnie od tekstu SQL. Oczekiwany wynik to dokładnie jeden wiersz zawierający 42.

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class Quickstart {
    public static void main(String[] args) throws SQLException {
        SQLServerDataSource dataSource = new SQLServerDataSource();
        dataSource.setServerName(required("SQL_SERVER_NAME"));
        dataSource.setDatabaseName(required("SQL_DATABASE_NAME"));
        dataSource.setPortNumber(Integer.parseInt(required("SQL_PORT")));
        dataSource.setEncrypt("true");
        dataSource.setTrustServerCertificate(false);
        dataSource.setLoginTimeout(30);

        String authentication = required("SQL_AUTHENTICATION");
        switch (authentication) {
            case "ActiveDirectoryInteractive":
            case "ActiveDirectoryManagedIdentity":
                break;
            case "SqlPassword":
                dataSource.setUser(required("SQL_USER"));
                dataSource.setPassword(required("SQL_PASSWORD"));
                break;
            default:
                throw new IllegalArgumentException(
                        "SQL_AUTHENTICATION must be ActiveDirectoryInteractive, "
                        + "ActiveDirectoryManagedIdentity, or SqlPassword.");
        }
        dataSource.setAuthentication(authentication);

        if (System.getenv("SQL_TRUST_STORE") != null
                || System.getenv("SQL_TRUST_STORE_PASSWORD") != null) {
            dataSource.setTrustStore(required("SQL_TRUST_STORE"));
            dataSource.setTrustStorePassword(required("SQL_TRUST_STORE_PASSWORD"));
            dataSource.setTrustStoreType("PKCS12");
        }

        String sql = "SELECT CAST(? AS int) + 1 AS answer";
        try (Connection connection = dataSource.getConnection();
             PreparedStatement statement = connection.prepareStatement(sql)) {
            statement.setInt(1, 41);
            statement.setQueryTimeout(30);
            try (ResultSet results = statement.executeQuery()) {
                if (!results.next() || results.getInt("answer") != 42 || results.next()) {
                    throw new SQLException("Expected exactly one row with answer = 42.");
                }
            }
        }
        System.out.println("Verified result: 42");
    }

    private static String required(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Set environment variable " + name + ".");
        }
        return value;
    }
}

Aplikacja ustawia limity logowania i zapytań na 30 sekund. Interaktywne uwierzytelnianie ma osobny limit oczekiwania na tokeny opisany w Troubleshoot the first run. Aplikacja zamyka zbiór wyników, przygotowaną instrukcję i połączenie za pomocą mechanizmu try-with-resources, także w przypadku wystąpienia wyjątku. Błędy się rozchodzą i powodują, że proces kończy się ze statusem niezerowym.

Uruchom i zweryfikowaj

Z katalogu jdbc-quickstart uruchom:

mvn -q compile exec:exec

Maven pobiera zależności, kompiluje aplikację i uruchamia osobny proces Java. Dla ActiveDirectoryInteractive, zakończ logowanie w przeglądarce i wróć do terminala.

Po pomyślnym zapytaniu i zamknięciu zasobów przez aplikację, wypisuje ona:

Verified result: 42

Komunikat przeglądarki o zakończeniu uwierzytelniania nie potwierdza, że połączenie z bazą danych się udało. Sprawdź wynik działania aplikacji i zerowy kod zakończenia: $LASTEXITCODE w programie PowerShell lub $? w Bash. Zapytanie nie zależy od istniejących tabel ani nie pozostawia danych do czyszczenia.

Jeśli użyto uwierzytelniania SQL, po zakończeniu usuń SQL_PASSWORD ze środowiska terminala. W programie PowerShell uruchom polecenie Remove-Item Env:\SQL_PASSWORD. W Bash uruchom unset SQL_PASSWORD.

Jeśli skonfigurowałeś magazyn zaufanych certyfikatów prywatnego urzędu certyfikacji (CA), usuń także powiązane z nim zmienne środowiskowe. W programie PowerShell uruchom polecenie Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD. W Bash uruchom unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD. Zachowaj magazyn powierniczy tylko tak długo, jak go potrzebujesz.

Rozwiązywanie problemów z pierwszym uruchomieniem

Dodatkowe informacje diagnostyczne znajdziesz w sekcji Rozwiązywanie problemów z łącznością.

Treści powiązane

• Połączenie przy użyciu uwierzytelniania Microsoft Entra
• Używanie instrukcji SQL z parametrami
• Korzystanie z automatycznie generowanych kluczy
• Odporność połączenia
• Przykładowe aplikacje sterowników JDBC