Snabbstart: Anslut till SQL Server med Java och Maven

Använd Microsoft Java Database Connectivity (JDBC)-drivrutinen för SQL Server för att koppla en Java applikation till SQL Server, Azure SQL Database eller SQL-databas i Fabric. Denna snabbstart använder Maven för att ladda ner beroenden, läser anslutningsinställningar från miljövariabler och verifierar ett parameteriserat frågeresultat. Du behöver inte AdventureWorks eller några exempeltabeller.

För Azure SQL Database eller SQL Database in Fabric, använd Microsoft Entra ID-autentisering utan att lagra ett lösenord i din applikation. Under lokal utveckling, logga in via en webbläsare. För en applikation som hostas i Azure, använd en hanterad identitet.

Förutsättningar

• Java Development Kit (JDK) 21. Kontrollera din installation med java -version.
• Apache Maven. Kör mvn -version och bekräfta att Maven använder JDK 21.
• En databas och behörighet att ansluta till den. Välj en hostad databas eller SQL Server-container i Välj din databas. Frågan läser ett beräknat värde och skapar eller ändrar inte databasobjekt.
• Nätverksåtkomst till din databas-endpoint. För Azure SQL, konfigurera nätverksåtkomst. För Fabric, gå till Anslut till din SQL-databas. För SQL Server, aktivera Transmission Control Protocol/Internet Protocol (TCP/IP) och använd den konfigurerade porten.
• Ett servercertifikat som din Java-runtime litar på. Applikationen kräver kryptering och validerar servercertifikatet. För en privat certifikatutfärdare, se Lita på en privat certifikatutfärdare.

Välj din databas

Använd en befintlig databas eller skapa en genom att använda följande guider. En tom databas räcker.

SQL Server Linux-containeravbildningar kräver en stödd x86-64-värd. På en ARM64-utvecklingsdator kan man köra denna Java-applikation mot en hostad databas eller en container på en stödd fjärrvärd istället för att förlita sig på containeremulering.

En ny container kan använda ett certifikat som din JDK inte litar på. Innan du kör detta exempel, konfigurera ett servercertifikat och, för en privat utfärdare, konfigurera Java trust store. Ha certifikatvalidering aktiverad för containeranslutningar också.

Skapa Maven-projektet

Skapa en katalog med namnet jdbc-quickstart. I den katalogen, skapa pom.xml med följande innehåll. Maven hanterar klassvägen; du behöver inte ladda ner Java Archive (JAR)-filer manuellt.

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

Förarartefakten jre11 fungerar med JDK 21. Den explicita azure-identity beroendet tillhandahåller autentiseringsbiblioteken som behövs för Microsoft Entra-lägena i denna snabbstart; dessa bibliotek är valfria beroenden till drivrutinen och läggs inte automatiskt till i din applikation.

Dessa versioner överensstämmer med den publicerade JDBC 13.6.0 Maven-projektobjektmodellen (POM). Det uttryckliga azure-core-http-netty-beroendet gör att den transportversion som valdes för den drivrutinsversionen behålls.

För drivrutinsuppdateringar, kolla nedladdningssidan, publicerade Maven-versioner och Java-stödmatris. När du uppdaterar drivrutinen, matcha autentiseringsberoendena med drivrutinens publicerade POM. Se Funktionsberoenden. Använd explicita releaseversioner istället för Maven-versionsintervall eller LATEST.

Konfigurera anslutningen

Ställ in miljövariablerna i samma terminal där du kör Maven. Ersätt <server> och <database> med ditt endpoint- och databasnamn. Ställ SQL_SERVER_NAME in endast på värdnamnet, utan någon JDBC-URL eller port.

Om det kopierade servervärdet är tcp:<server>,1433, använd endast <server> för SQL_SERVER_NAME och sätter SQL_PORT till 1433. Inkludera inte prefixet tcp: eller suffixet ,1433 i värdnamnet.

Azure SQL eller Fabric med Microsoft Entra-autentisering

För lokal utveckling, använd ActiveDirectoryInteractive. Drivrutinen öppnar en webbläsare för inloggning och stöder multifaktorautentisering. Logga in med den identitet som har tillgång till din databas. Sätt inte in SQL_USER eller SQL_PASSWORD för detta läge.

För Azure SQL Database, ersätt <server> med det fullständiga värdnamnet, såsom contoso.database.windows.net. För Fabric, kopiera värdnamnet från SQL-databasens anslutningsinställningar; konstruera det inte från databasnamnet eller lägg till ett Azure SQL-suffix. Fabric kräver Microsoft Entra-autentisering; använd inte exemplet med SQL-autentisering för 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"

För en applikation utan användargränssnitt som körs på en Azure-resurs med en systemtilldelad hanterad identitet:

1. Aktivera resursens hanterade identitet.
2. Be din administratör att ge den identiteten tillgång till databasen. För Azure SQL, skapa en databasanvändare för identiteten. För Fabric, följ Fabric-autentiserings- och åtkomstkrav, inklusive tillämpliga hyresgästinställningar för tjänstehuvudpersoner.
3. Ange SQL_AUTHENTICATION till ActiveDirectoryManagedIdentity i värdens applikationskonfiguration. Behåll server-, databas- och portinställningarna. Samma Java-applikation körs utan webbläsare eller lösenord.

Managed identity kräver en stödd Azure-värd; det är inte en ersättning för interaktiv inloggning på din arbetsstation. För användartilldelade identiteter och andra autentiseringslägen, se Anslut med Microsoft Entra-autentisering.

SQL Server med SQL-autentisering

För en SQL Server-container eller befintlig instans konfigurerad för SQL-autentisering, ställ SQL_AUTHENTICATION in och SqlPassword tillhandahåll en SQL-inloggning med tillgång till din databas. Använd inte ett serveradministratörskonto för detta exempel. PowerShell-lösenordsprompten kräver PowerShell 7.1 eller senare.

$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

Använd din instans TCP-port om den inte är 1433. Miljövariabler håller autentiseringsuppgifter utanför källkoden, men de är inte en säker lagringsplats för hemligheter. Logga inte dem eller lägg dem in i källkodskontroll. Aktivera inte Maven-debugloggning (-X) medan lösenordsvariabler är satta: exekveringspluginet loggar barnprocessens miljövärden. För distribuerade applikationer, använd plattformens inställningar för hemlig hantering och säker anslutning.

Lita på en privat certifikatutställare

Hoppa över denna sektion om din JDK redan litar på serverns certifikatutgivare. Annars, skaffa det offentliga certifikatet och SHA-256-fingeravtrycket från den utfärdande certifikatutnämnaren (CA) från din administratör via en betrodd kanal. Lita inte på ett certifikat bara för att servern visade det under en misslyckad anslutning.

Ställ SQL_SERVER_NAME in på ett DNS-namn som täcks av servercertifikatet och som kan lösas från din dator. Applikationen åsidosätter hostNameInCertificateinte , så drivrutinen validerar det konfigurerade servernamnet. Att lägga till en betrodd CA åtgärdar inte en felmatchning i certifikatnamnet.

Använd keytool från samma JDK 21-installation som Maven använder. Ersätt <ca-certificate-file> med den verifierade CA-certifikatets sökväg, <jdk-home> med den JDK:s katalog och <trust-store-file> med en ny absolut sökväg utanför ditt projekt. Behåll förtroendelagringen i en katalog som andra oprivilegierade användare inte kan ändra. Sluta om något kommando misslyckas.

1. Granska CA-certifikatet och jämför dess SHA-256-fingeravtryck med det värde din administratör angav.

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

2. Skapa en dedikerad PKCS12-förtroendebutik genom att kopiera JDK:s publika rötter. Ändra inte den installerade JDK:s cacerts fil eller skriv över en befintlig förtroendelagring.

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

   Ange ett nytt destinationsbutikslösenord vid promptarna. För lösenordet för källvarubutiken, använd värdet som tillhandahålls av din JDK-leverantör eller administratör. Att kopiera de publika rötterna behåller förtroendet för servrar som använder publika CA:er.

3. Lägg till den verifierade CA:n i den dedikerade butiken.

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

   Ange lösenordet till destinationsbutiken. Innan du bekräftar importen, kontrollera att det visade fingeravtrycket matchar det verifierade värdet.

Ställ in dessa två valfria variabler i terminalen där du kör Maven. Använd det destinationsbutikslösenord du just skapat. PowerShell-lösenordsprompten kräver PowerShell 7.1 eller senare.

$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

Java-applikationen läser dessa variabler och konfigurerar sin JDBC-förtroendelagring explicit. Utelämna båda variablerna för att använda Java Virtual Machines (JVM:s) standardförtroendekonfiguration. Behåll encrypt=true och trustServerCertificate=false.

Maven startar en separat Java-process för denna applikation. Att ange en egenskap för Java Secure Socket Extension (JSSE), såsom javax.net.ssl.trustStore med mvn -D... eller MAVEN_OPTS, konfigurerar inte den underordnade processen. JAVA_TOOL_OPTIONS och JDK_JAVA_OPTIONS når det, men JVM återger dessa alternativ vid uppstart. Sätt inte lösenord i någon av variablerna. Använd istället applikationsvariablerna i detta avsnitt. För mer om förtroendekonfiguration, se Konfigurera klienten för kryptering.

Lägg till Java-applikationen

Från katalogenjdbc-quickstart, skapa Java-källkatalogen.

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

mkdir -p src/main/java

Spara följande fullständiga applikation som Quickstart.java i src/main/java.

Transact-SQL (T-SQL)-frågan SELECT CAST(? AS int) + 1 AS answer accepterar en parameter. setInt binder värdet 41 separat från SQL-texten. Det förväntade resultatet är exakt en rad som innehåller 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;
    }
}

Applikationen sätter inloggnings- och frågetidsavbrott till 30 sekunder. Interaktiv autentisering har en separat token-väntegräns som beskrivs i Felsökning vid första körningen. Applikationen stänger resultatuppsättningen, förberedda satsen och anslutningen genom att använda try-with-resources, även när ett undantag inträffar. Fel fortplantar sig och gör att processen avslutas med en statuskod som inte är noll.

Kör och verifiera

Från katalogen jdbc-quickstart , kör:

mvn -q compile exec:exec

Maven laddar ner beroenden, kompilerar applikationen och startar en separat Java-process. För ActiveDirectoryInteractive, slutför inloggningen i webbläsaren och återvänd till din terminal.

Efter att förfrågan lyckats och applikationen stänger resurserna, skriver den ut:

Verified result: 42

Ett webbläsarmeddelande om att autentiseringen är klar bevisar inte att databasanslutningen lyckades. Kontrollera programmets resultat och att avslutningsstatusen är 0: $LASTEXITCODE i PowerShell eller $? i Bash. Frågan är inte beroende av några befintliga tabeller och lämnar inte kvar några data som behöver rensas upp.

Om du använde SQL-autentisering, ta bort SQL_PASSWORD från terminalmiljön när du är klar. Kör Remove-Item Env:\SQL_PASSWORD i PowerShell. I Bash, kör unset SQL_PASSWORD.

Om du konfigurerade en betrodd certifikatslagringsplats för en privat CA, ska du också ta bort dess miljövariabler. Kör Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD i PowerShell. I Bash, kör unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD. Behåll förtroendebutiken endast så länge du behöver den.

Felsök första körningen

För ytterligare diagnostik, se Felsökning av anslutning.

Relaterat innehåll

• Ansluta med Microsoft Entra-autentisering
• Använda en SQL-instruktion med parametrar
• Användning av automatiskt genererade nycklar
• Anslutningsmotståndskraft
• Exempel på JDBC-drivrutinsprogram