Démarrage rapide : Connectez-vous à SQL Server avec Java et Maven

Utilisez le pilote Microsoft Java Database Connectivity (JDBC) pour SQL Server afin de connecter une application Java à une base de données SQL Server, Azure SQL Database ou SQL dans Fabric. Ce démarrage rapide utilise Maven pour télécharger les dépendances, lit les paramètres de connexion à partir des variables d’environnement et vérifie un résultat de requête paramétrée. Vous n’avez pas besoin d’AdventureWorks ni de tables d’exemples.

Pour Azure SQL Database ou SQL Database dans Fabric, utilisez l’authentification Microsoft Entra ID sans stocker de mot de passe dans votre application. Pendant le développement local, connectez-vous via un navigateur. Pour une application hébergée dans Azure, utilisez une identité gérée.

Prerequisites

• Kit de développement Java (JDK) 21. Vérifiez votre installation avec java -version.
• Apache Maven. Exécutez mvn -version et confirmez que Maven utilise JDK 21.
• Une base de données et la permission de s’y connecter. Choisissez une base de données hébergée ou un conteneur SQL Server dans Choisissez votre base de données. La requête lit une valeur calculée et ne crée ni ne modifie les objets de la base de données.
• Accès réseau à votre point de terminaison de base de données. Pour Azure SQL, configurez l’accès réseau. Pour Fabric, suivez Se connecter à votre base de données SQL. Pour SQL Server, activez le protocole de contrôle de transmission/protocole Internet (TCP/IP) et utilisez le port configuré.
• Un certificat serveur auquel votre runtime Java fait confiance. L’application nécessite un chiffrement et valide le certificat serveur. Pour une autorité de certification privée, suivez Faire confiance à une autorité de certification privée.

Choisir votre base de données

Utilisez une base de données existante ou créez-en une en utilisant les guides suivants. Une base de données vide suffit.

Les images de conteneur Linux de SQL Server nécessitent un hôte x86-64 pris en charge. Sur un ordinateur de développement ARM64, exécutez cette application Java sur une base de données hébergée ou un conteneur sur un hôte distant supporté au lieu de dépendre de l’émulation de conteneur.

Un nouveau conteneur pourrait utiliser un certificat auquel votre JDK ne fait pas confiance. Avant d’exécuter cet exemple, configurez un certificat serveur et, pour un émetteur privé, configurez le magasin de confiance Java. Gardez aussi activé la validation des certificats pour les connexions de conteneurs.

Créer le projet Maven

Créez un répertoire nommé jdbc-quickstart. Dans ce répertoire, créez pom.xml avec le contenu suivant. Maven gère le chemin de classe ; vous n'avez pas besoin de télécharger manuellement des fichiers 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>

L’artefact jre11 du pilote est compatible avec JDK 21. La dépendance explicite azure-identity fournit les bibliothèques d'authentification nécessaires aux modes Microsoft Entra dans ce démarrage rapide ; ces bibliothèques sont des dépendances optionnelles du pilote et ne sont pas automatiquement ajoutées à votre application.

Ces versions correspondent au modèle d’objet du projet Maven (POM) JDBC 13.6.0 publié. La dépendance explicite azure-core-http-netty conserve la version de transport sélectionnée par cette version du pilote.

Pour les mises à jour des pilotes, consultez la page de téléchargement, les versions publiées de Maven et la matrice de support Java. Lorsque vous mettez à jour le pilote, associez les dépendances d’authentification au POM publié par le pilote. Voir Dépendances de fonctionnalités. Utilisez des versions explicites plutôt que des plages de versions Maven ou LATEST.

Configurez la connexion

Définissez les variables d’environnement dans le même terminal où vous utilisez Maven. Remplacez <server> et <database> avec le nom de votre endpoint et de la base de données. Définissez SQL_SERVER_NAME sur le seul nom d’hôte, sans URL JDBC ni port.

Si la valeur du serveur copié est tcp:<server>,1433, utilisez uniquement <server> pour SQL_SERVER_NAME et définissez SQL_PORT à 1433. N’incluez pas le préfixe ,1433 ni le suffixe tcp: dans le nom d’hôte.

Azure SQL ou Fabric avec authentification Microsoft Entra

Pour le développement local, utilisez ActiveDirectoryInteractive. Le pilote ouvre un navigateur pour la connexion et prend en charge l’authentification multifacteur. Connectez-vous avec l’identité qui a accès à votre base de données. Ne définissez pas SQL_USER ou SQL_PASSWORD pour ce mode.

Pour Azure SQL Database, remplacez <server> par le nom complet de l’hôte, tel que contoso.database.windows.net. Pour Fabric, copiez le nom de l'hôte depuis les paramètres de connexion de la base de données SQL ; ne le construisez pas à partir du nom de la base de données ni n'ajoutez un suffixe Azure SQL. Fabric nécessite une authentification Microsoft Entra ; n'utilisez pas l'exemple d'authentification SQL pour 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"

Pour une application headless hébergée sur une ressource Azure avec une identité managée attribuée par le système :

1. Activez l’identité gérée de la ressource.
2. Demandez à votre administrateur d’accorder à cette identité l’accès à la base de données. Pour Azure SQL, créez un utilisateur de base de données pour l’identité. Pour Fabric, respectez les exigences d’authentification et d’accès Fabric, y compris les paramètres de locataire applicables pour les principaux de service.
3. Réglez SQL_AUTHENTICATION sur ActiveDirectoryManagedIdentity dans la configuration de l’application de l’hôte. Gardez les paramètres du serveur, de la base de données et des ports. La même application Java fonctionne sans navigateur ni mot de passe.

L'identité gérée nécessite un hôte Azure supporté ; ce n'est pas un substitut à la connexion interactive sur votre poste de travail. Pour les identités attribuées par l’utilisateur et autres modes d’authentification, voir Connecter avec l’authentification Microsoft Entra.

SQL Server avec authentification SQL

Pour un conteneur SQL Server ou une instance existante configurée pour l’authentification SQL, configurez SQL_AUTHENTICATION et SqlPassword fournissez une connexion SQL avec accès à votre base de données. N’utilisez pas un compte administrateur serveur pour cet exemple. L’invite de mot de passe PowerShell nécessite PowerShell 7.1 ou une version ultérieure.

$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

Utilisez le port TCP de votre instance si ce n’est pas le 1433. Les variables d’environnement empêchent les identifiants d’entrer dans le code source, mais ce ne sont pas un magasin secret. Ne les enregistrez pas et ne les mettez pas en contrôle de version. N’activez pas la journalisation de débogage de Maven (-X) lorsque des variables de mot de passe sont définies : le plugin d’exécution consigne les valeurs des variables d’environnement du processus enfant. Pour les applications déployées, utilisez les paramètres de gestion des secrets et de connexion sécurisée de votre plateforme.

Faites confiance à une autorité de certification privée

Saute cette section si ton JDK fait déjà confiance à l’émetteur du certificat du serveur. Sinon, obtenez le certificat public et l’empreinte digitale SHA-256 de l’autorité de certification émettrice (CA) auprès de votre administrateur via un canal de confiance. Ne faites pas confiance à un certificat simplement parce que le serveur l’a présenté lors d’une défaillance de connexion.

Réglez SQL_SERVER_NAME sur un nom DNS couvert par le certificat serveur et résoluble depuis votre ordinateur. L’application ne remplace hostNameInCertificatepas, donc le pilote valide le nom du serveur configuré. Ajouter une autorité de certification de confiance ne corrige pas un inadéquation entre le nom du certificat.

Utilisez la keytool issue de la même installation de JDK 21 que celle utilisée par Maven. Remplacez-le <ca-certificate-file> par le chemin du certificat CA vérifié, <jdk-home> par le répertoire de ce JDK, et <trust-store-file> par un nouveau chemin absolu en dehors de votre projet. Gardez le magasin de confiance dans un répertoire que les autres utilisateurs non privilégiés ne peuvent pas modifier. Arrêtez si une commande échoue.

1. Inspectez le certificat CA et comparez son empreinte digitale SHA-256 avec la valeur fournie par votre administrateur.

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

2. Créez un magasin de confiance dédié à PKCS12 en copiant les racines publiques du JDK. Ne modifiez pas le fichier cacerts du JDK installé et n'écrasez pas un magasin de confiance existant.

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

   Saisissez un nouveau mot de passe pour le magasin de destination lorsqu’il vous y est invité. Pour le mot de passe source-store, utilisez la valeur fournie par votre fournisseur JDK ou votre administrateur. La copie des certificats racines publics préserve la confiance accordée aux serveurs qui utilisent des autorités de certification publiques.

3. Ajoutez l’autorité de certification vérifiée au magasin dédié.

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

   Entrez le mot de passe du magasin de destination. Avant de confirmer l’importation, vérifiez que l’empreinte digitale affichée correspond à la valeur vérifiée.

Définissez ces deux variables optionnelles dans le terminal où vous utilisez Maven. Utilisez le mot de passe du magasin de destination que vous venez de créer. L’invite de mot de passe PowerShell nécessite PowerShell 7.1 ou une version ultérieure.

$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

L’application Java lit ces variables et configure explicitement son magasin de confiance JDBC. Omettez les deux variables pour utiliser la configuration de confiance par défaut de la machine virtuelle Java (JVM). Garder encrypt=true et trustServerCertificate=false.

Maven lance un processus Java séparé pour cette application. Définir une propriété Java Secure Socket Extension (JSSE) telle que javax.net.ssl.trustStore avec mvn -D... ou MAVEN_OPTS ne configure pas ce processus enfant. JAVA_TOOL_OPTIONS et JDK_JAVA_OPTIONS y accèdent, mais la JVM affiche ces options au démarrage. Ne mettez pas de mots de passe dans aucune des variables. Utilisez plutôt les variables d’application de cette section. Pour en savoir plus sur la configuration de la confiance, voir Configurer le client pour le chiffrement.

Ajouter l’application Java

Depuis le jdbc-quickstart répertoire, créez le répertoire source Java.

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

mkdir -p src/main/java

Conservez l’application complète suivante comme Quickstart.java dans src/main/java.

La requête SELECT CAST(? AS int) + 1 AS answer Transact-SQL (T-SQL) accepte un paramètre. setInt lie la valeur 41 séparément du texte SQL. Le résultat attendu est exactement une ligne contenant 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;
    }
}

L’application fixe les délais de connexion et de requête à 30 secondes. L’authentification interactive comporte un délai d’attente distinct pour les jetons, décrit dans Résoudre les problèmes liés à la première exécution. L’application ferme l’ensemble de résultats, l’instruction préparée et la connexion en utilisant try-with-resources, y compris lorsqu’une exception survient. Les erreurs se propagent et provoquent la sortie du processus avec un statut non nul.

Exécuter et vérifier

Depuis le jdbc-quickstart répertoire, exécutez :

mvn -q compile exec:exec

Maven télécharge les dépendances, compile l’application et lance un processus Java séparé. Pour ActiveDirectoryInteractive, terminez la connexion du navigateur et revenez à votre terminal.

Après que la requête a réussi et que l’application ferme les ressources, elle imprime :

Verified result: 42

Un message du navigateur indiquant que l’authentification est complète ne prouve pas que la connexion à la base de données a réussi. Vérifiez le résultat de l’application et un statut de sortie zéro : $LASTEXITCODE dans PowerShell ou $? dans Bash. La requête ne dépend pas d’aucune table existante ni ne laisse les données à nettoyer.

Si vous avez utilisé l’authentification SQL, retirez-le SQL_PASSWORD de l’environnement terminal une fois terminé. Dans PowerShell, exécutez Remove-Item Env:\SQL_PASSWORD. Dans Bash, exécutez unset SQL_PASSWORD.

Si vous configurez un magasin de confiance en CA privée, supprimez également ses variables d’environnement. Dans PowerShell, exécutez Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD. Dans Bash, exécutez unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD. Conservez le magasin de fiducie seulement tant que vous en avez besoin.

Résoudre les problèmes liés à la première exécution

Pour des diagnostics complémentaires, voir Dépannage de la connectivité.

Contenu connexe

• Se connecter à l’aide de l’authentification Microsoft Entra
• Utilisation d'une instruction SQL avec des paramètres
• Utilisation de clés auto-générées
• Résilience des connexions
• Exemples d'applications du pilote JDBC