Quickstart: Verbind met SQL Server met Java en Maven

Gebruik de Microsoft Java Database Connectivity (JDBC) Driver voor SQL Server om een Java applicatie te verbinden met SQL Server, Azure SQL Database of SQL-database in Fabric. Deze quickstart gebruikt Maven om afhankelijkheden te downloaden, leest verbindingsinstellingen uit omgevingsvariabelen en verifieert een geparametriseerd queryresultaat. Je hebt geen AdventureWorks of voorbeeldtabellen nodig.

Voor Azure SQL Database of SQL Database in Fabric gebruik je Microsoft Entra ID-authenticatie zonder een wachtwoord in je applicatie op te slaan. Log tijdens lokale ontwikkeling in via een browser. Voor een applicatie die in Azure wordt gehost, gebruik een beheerde identiteit.

Prerequisites

• Java Development Kit (JDK) 21. Controleer je installatie met java -version.
• Apache Maven. Voer het uit mvn -version en bevestig dat Maven JDK 21 gebruikt.
• Een database en toestemming om ermee te verbinden. Kies een gehoste database of SQL Server-container in Choose your database. De query leest een berekende waarde en maakt geen databaseobjecten aan of wijzigt ze niet.
• Netwerktoegang tot je database-endpoint. Voor Azure SQL, configureer je netwerktoegang. Volg voor Fabric de instructies in Verbinding maken met uw SQL-database. Voor SQL Server schakel je Transmission Control Protocol/Internet Protocol (TCP/IP) in en gebruik je de geconfigureerde poort.
• Een servercertificaat dat door je Java-runtime als betrouwbaar wordt beschouwd. De applicatie vereist encryptie en valideert het servercertificaat. Voor een privécertificaatautoriteit raadpleeg je Een privécertificaatautoriteit vertrouwen.

Uw database kiezen

Gebruik een bestaande database of maak er een aan met behulp van de volgende gidsen. Een lege database is voldoende.

SQL Server Linux containerimages vereisen een ondersteunde x86-64 host. Op een ARM64-ontwikkelcomputer kunt u deze Java-applicatie uitvoeren op een gehoste database of een container op een ondersteunde externe host in plaats van te vertrouwen op containeremulatie.

Een nieuwe container kan een certificaat gebruiken dat je JDK niet vertrouwt. Voordat je dit voorbeeld uitvoert, configureer je een servercertificaat en, voor een private uitgever, de Java trust store. Houd certificaatvalidatie ook ingeschakeld voor containerverbindingen.

Creëer het Maven-project

Maak een map met de naam jdbc-quickstart. Maak in die directory pom.xml met de volgende inhoud. Maven beheert het klassepad; je hoeft geen Java archive (JAR) bestanden handmatig te downloaden.

<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>

Het jre11 driver-artefact werkt met JDK 21. De expliciete azure-identity afhankelijkheid levert de authenticatiebibliotheken die nodig zijn voor de Microsoft Entra-modi in deze quickstart; die bibliotheken zijn optionele afhankelijkheden van de driver en worden niet automatisch aan je applicatie toegevoegd.

Deze versies komen overeen met het gepubliceerde JDBC 13.6.0 Maven project object model (POM). De expliciete azure-core-http-netty afhankelijkheid behoudt de transportversie die door die driverrelease is geselecteerd.

Voor driverupdates, bekijk de downloadpagina, gepubliceerde Maven-versies en de Java-ondersteuningsmatrix. Wanneer je de driver bijwerkt, koppel dan de authenticatieafhankelijkheden aan de gepubliceerde POM van de driver. Zie afhankelijkheden van functies. Gebruik expliciete releaseversies in plaats van Maven-versiereeksen of LATEST.

Configureer de verbinding

Stel de omgevingsvariabelen in in dezelfde terminal waar je Maven draait. Vervang <server> en <database> door je endpoint en databasenaam. Stel SQL_SERVER_NAME in op alleen de hostnaam, zonder een JDBC-URL of poort.

Als de gekopieerde serverwaarde is tcp:<server>,1433, gebruik alleen <server> voor SQL_SERVER_NAME en zet SQL_PORT op 1433. Voeg het tcp: voorvoegsel of ,1433 achtervoegsel niet toe in de hostnaam.

Azure SQL of Fabric met Microsoft Entra-authenticatie

Voor lokale ontwikkeling, gebruik ActiveDirectoryInteractive. De driver opent een browser voor aanmelden en ondersteunt multifactorauthenticatie. Log in met de identiteit die toegang heeft tot je database. Stel deze modus niet in.SQL_USERSQL_PASSWORD

Voor Azure SQL Database, vervang <server> door de volledige hostnaam, zoals contoso.database.windows.net. Voor Fabric kopieer je de hostnaam uit de verbindingsinstellingen van de SQL-database; construeer het niet vanuit de databasenaam of voeg een Azure SQL-achtervoegsel toe. Fabric vereist Microsoft Entra-authenticatie; gebruik het SQL-authenticatievoorbeeld niet voor 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"

Voor een headless applicatie die wordt gehost op een Azure-resource met een systeem-toegewezen beheerde identiteit:

1. Schakel de beheerde identiteit van de resource in.
2. Vraag je beheerder om die identiteit toegang tot de database te geven. Voor Azure SQL maak je een databasegebruiker aan voor de identiteit. Voor Fabric volgt u de Fabric-authenticatie- en toegangseisen, inclusief de toepasselijke tenantinstellingen voor service principals.
3. Stel SQL_AUTHENTICATION in op ActiveDirectoryManagedIdentity in de applicatieconfiguratie van de host. Houd de server-, database- en poortinstellingen behouden. Dezelfde Java-applicatie draait zonder browser of wachtwoord.

Beheerde identiteit vereist een ondersteunde Azure-host; het is geen vervanging voor interactieve aanmelding op je werkstation. Voor door gebruikers toegewezen identiteiten en andere authenticatiemodi, zie Connect met Microsoft Entra-authenticatie.

SQL Server met SQL-authenticatie

Voor een SQL Server-container of een bestaande instantie die is geconfigureerd voor SQL-authenticatie, stel SQL_AUTHENTICATION in op SqlPassword en geef een SQL-login op met toegang tot je database. Gebruik geen serverbeheerdersaccount voor dit voorbeeld. De PowerShell-wachtwoordprompt vereist PowerShell 7.1 of later.

$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

Gebruik de TCP-poort van je instantie als die niet 1433 is. Omgevingsvariabelen houden inloggegevens uit de broncode, maar ze zijn geen geheime opslag. Log ze niet en zet ze niet in bij source control. Schakel Maven debuglogging (-X) niet in terwijl wachtwoordvariabelen zijn ingesteld: de uitvoeringsplugin logt de omgevingswaarden van het kindproces. Voor gedeployeerde applicaties gebruik je de geheime beheer- en veilige verbindingsinstellingen van je platform.

Vertrouw op een particuliere certificaatautoriteit

Sla dit gedeelte over als je JDK al de certificaatuitgever van de server vertrouwt. Anders kun je het publieke certificaat en de SHA-256 vingerafdruk van de uitgevende certificaatautoriteit (CA) van je beheerder via een vertrouwd kanaal verkrijgen. Vertrouw een certificaat niet alleen omdat de server het heeft getoond tijdens een mislukte verbinding.

Stel het in SQL_SERVER_NAME op een DNS-naam die door het servercertificaat wordt beschermd en die vanaf je computer kan worden opgelost. De applicatie overschrijft hostNameInCertificateniet, dus valideert de driver de geconfigureerde servernaam. Het toevoegen van een vertrouwde CA lost geen mismatch tussen certificaatnamen op.

Gebruik de keytool uit dezelfde JDK 21-installatie die Maven gebruikt. Vervang <ca-certificate-file> door het pad van het geverifieerde CA-certificaat, <jdk-home> door de map van die JDK, en <trust-store-file> door een nieuw absoluut pad buiten je project. Houd de trust store in een map die andere niet-privilegede gebruikers niet kunnen wijzigen. Stop als een commando faalt.

1. Controleer het CA-certificaat en vergelijk de SHA-256 vingerafdruk met de waarde die je beheerder heeft opgegeven.

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

2. Maak een speciale PKCS12 trustopslag aan door de publieke wortels van de JDK te kopiëren. Verander het geïnstalleerde JDK-bestand cacerts niet en overschrijf geen bestaande trustopslag.

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

   Voer een nieuw bestemmingswinkelwachtwoord in bij de prompts. Voor het source-store wachtwoord gebruik je de waarde die door je JDK-provider of beheerder wordt opgegeven. Het kopiëren van de publieke roots behoudt het vertrouwen voor servers die publieke CA's gebruiken.

3. Voeg de geverifieerde CA toe aan de speciale winkel.

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

   Voer het wachtwoord van de bestemmingswinkel in. Controleer voordat je de import bevestigt of de weergegeven vingerafdruk overeenkomt met de geverifieerde waarde.

Stel deze twee optionele variabelen in in de terminal waar je Maven draait. Gebruik het bestemmingswinkelwachtwoord dat je zojuist hebt aangemaakt. De PowerShell-wachtwoordprompt vereist PowerShell 7.1 of later.

$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

De Java-applicatie leest deze variabelen en configureert expliciet zijn JDBC trust store. Beide variabelen weglaten om de standaard vertrouwensconfiguratie van de Java Virtual Machine (JVM) te gebruiken. Behoud encrypt=true en trustServerCertificate=false.

Maven start een apart Java-proces voor deze applicatie. Het instellen van een Java Secure Socket Extension (JSSE)-eigenschap zoals javax.net.ssl.trustStore met mvn -D... of MAVEN_OPTS configureert dat childproces niet. JAVA_TOOL_OPTIONS en JDK_JAVA_OPTIONS het bereiken, maar de JVM weerspiegelt die opties bij de opstart. Zet geen wachtwoorden in een van beide variabelen. Gebruik in plaats daarvan de applicatievariabelen in deze sectie. Voor meer over trustconfiguratie, zie Configureer de client voor encryptie.

Voeg de Java-applicatie toe

Maak vanuit de jdbc-quickstart map de Java-bronmap aan.

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

mkdir -p src/main/java

Sla de volgende volledige applicatie op als Quickstart.java in src/main/java.

De Transact-SQL (T-SQL) query SELECT CAST(? AS int) + 1 AS answer accepteert één parameter. setInt bindt de waarde 41 apart van de SQL-tekst. Het verwachte resultaat is precies één rij die bevat 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;
    }
}

De applicatie stelt de time-outs voor inlogen en query's in op 30 seconden. Interactieve authenticatie heeft een aparte token-wachtlimiet zoals beschreven in Troubleshoot the first run. De applicatie sluit de resultaatset, de voorbereide instructie en de verbinding door gebruik te maken van try-with-resources, ook wanneer er een uitzondering optreedt. Fouten verspreiden zich en zorgen ervoor dat het proces wordt afgesloten met een niet-nul status.

Voer het uit en verifieer

Voer vanuit de jdbc-quickstart directory uit:

mvn -q compile exec:exec

Maven downloadt de afhankelijkheden, compileert de applicatie en start een apart Java-proces. Voor ActiveDirectoryInteractive, voltooi de browser-inloggegevens en ga terug naar je terminal.

Nadat de query slaagt en de applicatie de resources sluit, print het:

Verified result: 42

Een browserbericht dat de authenticatie voltooid is, bewijst niet dat de databaseverbinding is geslaagd. Controleer of de toepassing resultaat oplevert en een exitstatus van nul heeft: $LASTEXITCODE in PowerShell of $? in Bash. De query is niet afhankelijk van eventuele bestaande tabellen en laat geen gegevens achter die moeten worden opgeschoond.

Als je SQL-authenticatie hebt gebruikt, verwijder SQL_PASSWORD het dan uit de terminalomgeving als je klaar bent. Voer in PowerShell Remove-Item Env:\SQL_PASSWORD uit. Voer in Bash unset SQL_PASSWORD uit.

Als je een private-CA trustopslag hebt geconfigureerd, verwijder dan ook de omgevingsvariabelen ervan. Voer in PowerShell Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD uit. Voer in Bash unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD uit. Behoud de trust store alleen zolang je hem nodig hebt.

Problemen bij de eerste uitvoering oplossen

Raadpleeg voor aanvullende diagnose Problemen met de connectiviteit oplossen.

Verwante onderwerpen

• Verbinding maken door gebruik te maken van Microsoft Entra-verificatie
• Een SQL-instructie gebruiken met parameters
• Gebruik van automatisch gegenereerde sleutels
• Verbindingstolerantie
• Voorbeeld van JDBC-stuurprogrammatoepassingen