クイックスタート:JavaとMavenでSQL Serverに接続

SQL Server Microsoft Javaデータベース接続性(JDBC)ドライバーを使用して、JavaアプリケーションをFabricのSQL Server、Azure SQL Database、またはSQLデータベースに接続します。このクイックスタートは、Mavenを使って依存関係のダウンロード、環境変数から接続設定の読み取り、パラメータ化されたクエリ結果の検証を行います。 AdventureWorksやサンプルテーブルは必要ありません。

Azure SQL DatabaseやFabricのSQLデータベースでは、アプリケーション内にパスワードを保存せずにMicrosoft Entra ID認証を使いましょう。ローカル開発中はブラウザからサインインしてください。 Azureでホストされたアプリケーションには、マネージドアイデンティティを使いましょう。

前提条件

Java開発キット(JDK)21. java -versionでインストールを確認してください。
Apache Maven。 mvn -version を実行し、Maven が JDK 21 を使用していることを確認してください。
データベースと接続許可。「Choose your database」でホストデータベースまたはSQL Serverコンテナを選択します。クエリは計算された値を読み取り、データベースオブジェクトを作成・修正しません。
データベースエンドポイントへのネットワークアクセス。 Azure SQLの場合は、ネットワークアクセスを設定してください。 Fabricについては、SQLデータベースのConnectを選んでください。 SQL Serverでは、伝送制御プロトコル/インターネットプロトコル(TCP/IP)を有効にし、設定済みのポートを使用します。
Javaランタイムが信頼するサーバー証明書です。アプリケーションは暗号化を必要とし、サーバー証明書を検証します。プライベートの証明書発行機関の場合は、プライベート認証機関を信頼してください。

データベースの選択

既存のデータベースを使うか、以下のガイドを使って作成してください。空のデータベースで十分です。

Database	セットアップとアクセス
Fabric の SQL データベース	SQLデータベースを作成し、その後Fabricの認証とアクセス要件に従います。設定>接続文字列からデータベースのサーバー名とデータベース名をコピーします。 SQL データベース接続を使用し、その SQL アナリティクスエンドポイントは使用しないでください。
Azure SQL Database	単一データベースを作成します。管理者にMicrosoft Entra管理者を設定し、あなたのID用のデータベースユーザーを作成するよう依頼してください。 Azureのサブスクリプションアクセスだけではデータベースへのアクセスは認められません。
SQL Server コンテナ	Docker、sqlcmd、またはVisual Studio CodeのMSSQL拡張機能を使ってコンテナを作成しましょう。コンテナホストのDNS名と公開されたTCPポート、そしてデータベースへの接続権限付きのSQLログインを使いましょう。
既存のSQL Server	インスタンスのDNS名、TCPポート、既存のデータベースを使ってください。管理者にSQLログインを依頼し、接続の許可を得てください。

SQL ServerのLinuxコンテナイメージは、サポートされているx86-64ホストが必要です。 ARM64開発コンピュータ上で、コンテナエミュレーションに頼らず、ホストされたデータベースやサポートされたリモートホスト上のコンテナに対してこのJavaアプリケーションを実行できます。

新しいコンテナはJDKが信用しない証明書を使うかもしれません。このサンプルを実行する前に、サーバー証明書を設定し、プライベート発行者の場合はJavaトラストストアを設定してください。コンテナ接続でも証明書検証を有効にしておきましょう。

メイヴンプロジェクトを作ろう

jdbc-quickstart という名前のディレクトリを作成します。そのディレクトリで、以下の内容で pom.xml を作成します。 Mavenはクラスパスを管理します。Javaアーカイブ(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>

jre11ドライバーのアーティファクトはJDK 21で動作します。明示的な azure-identity 依存関係は、このクイックスタートのMicrosoft Entraモードに必要な認証ライブラリを提供しますが、これらのライブラリはドライバーのオプション依存であり、自動的にアプリケーションに追加されるわけではありません。

これらのバージョンは公開されている JDBC 13.6.0のMavenプロジェクトオブジェクトモデル(POM)に準拠しています。明示的な azure-core-http-netty 依存関係は、そのドライバーリリースで選択されたトランスポートバージョンを保持します。

ドライバーのアップデートについては、ダウンロードページ、公開されたMavenバージョン、Javaサポートマトリックスを確認してください。ドライバーを更新する際は、認証依存関係をドライバーの公開POMと一致させます。機能の依存関係を参照してください。 Mavenのバージョン範囲や LATESTではなく、明示的なリリース版を使用してください。

接続の設定

環境変数はMavenを実行する同じターミナルで設定してください。 <server>と<database>をエンドポイント名とデータベース名に置き換えてください。 SQL_SERVER_NAMEホスト名のみに設定し、JDBCのURLやポートは設定しません。

コピーしたサーバー値がtcp:<server>,1433の場合は、SQL_SERVER_NAMEには<server>のみを使用し、SQL_PORTを1433に設定します。ホスト名に tcp: の接頭辞や ,1433 接尾辞を入れないでください。

Microsoft Entra 認証を使用する Azure SQL または Fabric

地域開発には ActiveDirectoryInteractiveを使いましょう。ドライバーはサインイン用のブラウザを開き、多要素認証をサポートします。データベースにアクセスできるIDでサインインしてください。このモードで SQL_USER や SQL_PASSWORD を設定しないでください。

Azure SQL Databaseの場合は、<server>をcontoso.database.windows.netなどの完全なホスト名に置き換えてください。 Fabricの場合は、SQLデータベースの接続設定からホスト名をコピーしてください。データベース名から構成したり、Azure SQLのサフィックスを付けたりしないでください。 FabricはMicrosoft Entra認証が必要ですが、FabricのSQL認証例は使わないでください。

PowerShell
Bash

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

システムに割り当てられたマネージドアイデンティティを持つAzureリソース上でホストされたヘッドレスアプリケーションの場合:

リソースの管理されるアイデンティティを有効にしてください。
管理者にそのIDをデータベースへのアクセス権で許可してもらうよう依頼してください。 Azure SQLの場合は、アイデンティティ用のデータベースユーザーを作成します。 Fabric では、サービスプリンシパルに適用されるテナント設定を含むFabric の認証およびアクセス要件に従ってください。
ホストのアプリケーション設定で SQL_AUTHENTICATION を ActiveDirectoryManagedIdentity に設定してください。サーバー、データベース、ポート設定はそのままにしてください。同じJavaアプリケーションはブラウザやパスワードなしで動作します。

マネージドIDはサポートされているAzureホストを必要としますが、ワークステーションでのインタラクティブサインインの代わりにはなりません。ユーザー割り当てのIDやその他の認証モードについては、「Microsoft Entra認証を使ったConnect」を参照してください。

SQL認証付きSQL Server

SQL ServerコンテナやSQL認証用に設定された既存インスタンスの場合、SQL_AUTHENTICATIONをSqlPasswordに設定し、データベースへのアクセス権を持つSQLログインを提供します。このサンプルではサーバー管理者アカウントは使わないでください。 PowerShellパスワードプロンプトはPowerShell 7.1以降が必要です。

PowerShell
Bash

$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

1433でなければ、インスタンスのTCPポートを使ってください。環境変数は認証情報をソースコードから排除しますが、秘密のストアではありません。ログに残したりソース管理にコミットしたりしないでください。パスワード変数が設定されている間はMavenのデバッグログ(-X)を有効にしないでください。実行プラグインは子プロセスの環境値をログに記録します。展開されたアプリケーションでは、プラットフォームのシークレット管理と安全な接続設定を活用してください。

民間の証明書機関を信頼してください

もしJDKがすでにサーバーの証明書発行者を信頼しているなら、このセクションは飛ばしてください。それ以外の場合は、管理者から信頼できるチャネルを通じて発行証明書発行機関(CA)の公開証明書とSHA-256指紋を取得してください。接続失敗時にサーバーが証明書を提示したからといって、証明書を信用しないでください。

SQL_SERVER_NAME を、サーバー証明書の対象となっており、お使いのコンピューターから名前解決できる DNS 名に設定してください。アプリケーションは hostNameInCertificateを上書きしないため、ドライバーは設定されたサーバー名を検証します。信頼できるCAを追加しても証明書名の不一致は解決しません。

Mavenが使っているのと同じJDK 21インストールの keytool を使いましょう。 <ca-certificate-file>を認証済みのCA証明書のパスに置き換え、<jdk-home>そのJDKのディレクトリに、プロジェクト外の新しい絶対パスに<trust-store-file>してください。信頼ストアは他の非特権ユーザーが変更できないディレクトリに保管してください。コマンドが失敗したら停止してください。

CA証明書を確認し、SHA-256の指紋と管理者が提供した値を比較してください。
```
keytool -printcert -file "<ca-certificate-file>"
```
JDKの公開ルートをコピーして専用のPKCS12トラストストアを作成します。インストール済みのJDKの cacerts ファイルを改変したり、既存のトラストストアを上書きしたりしないでください。
```
keytool -importkeystore -srckeystore "<jdk-home>/lib/security/cacerts" -destkeystore "<trust-store-file>" -deststoretype PKCS12
```
表示されたプロンプトに従って、新しいデスティネーションストアのパスワードを入力します。ソースストアパスワードについては、JDKプロバイダーまたは管理者が提供する値を使用してください。パブリックルートをコピーすることで、パブリックCAを使用するサーバーの信頼が保たれます。
認証済みのCAを専用ストアに追加してください。
```
keytool -importcert -alias sql-server-ca -file "<ca-certificate-file>" -keystore "<trust-store-file>" -storetype PKCS12
```
宛先ストアのパスワードを入力します。インポートを確認する前に、表示される指紋が検証済みの数値と一致しているか確認してください。

Mavenを実行するターミナルでこれら2つのオプション変数を設定してください。さっき作成した宛先ストアのパスワードを使ってください。 PowerShellパスワードプロンプトはPowerShell 7.1以降が必要です。

PowerShell
Bash

$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アプリケーションはこれらの変数を読み取り、JDBC信頼ストアを明示的に設定します。両方の変数を省略して、Java仮想マシン(JVM)のデフォルトの信頼設定を使います。 encrypt=trueと、trustServerCertificate=falseを保って。

Mavenはこのアプリケーション用に別のJavaプロセスを開始します。 mvn -D...やMAVEN_OPTSでjavax.net.ssl.trustStoreのようなJava Secure Socket Extension(JSSE)プロパティを設定しても、その子プロセスは設定されません。 JAVA_TOOL_OPTIONS と JDK_JAVA_OPTIONS はそれに到達しますが、JVM は起動時にそれらのオプションを表示します。どちらの変数にもパスワードを入れないでください。このセクションのアプリケーション変数を使いましょう。信頼設定の詳細については、「暗号化のためのクライアントの設定」を参照してください。

Javaアプリケーションを追加してください

jdbc-quickstartディレクトリからJavaソースディレクトリを作成します。

PowerShell
Bash

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

mkdir -p src/main/java

以下の完全な申請書はsrc/main/javaQuickstart.javaとして保存してください。

Transact-SQL(T-SQL)クエリ SELECT CAST(? AS int) + 1 AS answer 1つのパラメータを受け入れます。 setInt SQLテキストとは別に値 41 をバインドします。期待される結果は、 42を含む行がちょうど1行です。

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

アプリケーションはログインとクエリのタイムアウトを30秒に設定します。インタラクティブ認証には、最初の実行のトラブルシューティングで説明された別のトークン待機制限があります。アプリケーションはtry-with-resourcesを使って結果セット、準備済み文、接続を閉じます。例外が発生した場合も含まれます。エラーが伝播し、プロセスはゼロでない状態で終了します。

走って確認してください

jdbc-quickstart ディレクトリから、次を実行します。

mvn -q compile exec:exec

Mavenは依存関係をダウンロードし、アプリケーションをコンパイルし、別のJavaプロセスを起動します。 ActiveDirectoryInteractiveするには、ブラウザのサインインを完了し、端末に戻ってください。

クエリが成功し、アプリケーションがリソースを閉じた後、次のように出力されます:

Verified result: 42

認証が完了したというブラウザのメッセージだけでは、データベース接続が成功したとは限りません。アプリケーションの結果と終了ステータスがゼロかどうかを確認してください:PowerShellで $LASTEXITCODE 、Bashで $? 。クエリは既存のテーブルに依存しず、データを整理する必要もありません。

SQL認証を使っているなら、終わったら端末環境から SQL_PASSWORD を削除してください。 PowerShell で、Remove-Item Env:\SQL_PASSWORD を実行します。 Bash で unset SQL_PASSWORD を実行します。

private-CAのトラストストアを設定した場合は、その環境変数も削除してください。 PowerShell で、Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD を実行します。 Bash で unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD を実行します。信託ストアは必要な期間だけ保持してください。

初回実行時のトラブルシューティング

症状:	アクション
`Set environment variable ...`	Mavenを実行するターミナルで名前付き変数を設定します。統合開発環境(IDE)は独自の実行構成を必要とする場合があります。
Javaコンパイルまたはクラスバージョンエラー	`mvn -version` を実行して、Maven が JDK 21 を使用していることを確認してください。 Mavenと`java -version`が異なるランタイムを報告しているか`JAVA_HOME`確認してください。
認証ライブラリが欠落しています	`azure-identity`依存関係を`pom.xml`に残し、アプリケーションをMavenで実行して推移依存関係を含めてください。
ログインタイムアウトまたは接続拒否	サーバーホスト名、TCPポート、データベースの可用性、ネットワークアクセスを確認してください。
対話型サインインがタイムアウトする	ドライバーはインタラクティブなトークンリクエストを最大20秒待ちます。サインインを完了してください。リクエストがタイムアウトしたら、再度コマンドを実行してください。 `loginTimeout`を増やしてもこのトークンの待機制限は延長されません。
Microsoft Entraのサインインは成功しますが、データベースアクセスは失敗します	正しいテナントにサインインしたこと、そして選択したデータベースへのアクセス権を自分のIDで確認してください。 Azure SQLデータベースのユーザーやFabricの権限を確認してください。
証明書の検証が失敗する（`PKIX path building failed` を含む）	プライベート発行者については、プライベート証明機関を信頼するに従ってください。サーバー証明書でカバーされているDNS名を使って接続してください。 `trustServerCertificate=true`で検証を無視しないでください。

追加の診断については、「接続のトラブルシューティング」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-21