ODBC は、C と C++ で記述された SQL Server 用アプリケーションのプライマリ ネイティブ データ アクセス API です。 Microsoft ODBC Driver for SQL Serverは、Microsoft Fabricの SQL Server、Azure SQL Database、Azure SQL Managed Instance、Azure Synapse Analytics、SQL データベースに接続しています。 各ドライバーリリースがサポートするデータベースバージョンについては、 SQLバージョン互換性を参照してください。
他には、COBOL、Perl、PHP、Python などの言語で ODBC を使用できます。 ODBCはデータ統合のシナリオで広く使われており、Microsoft Drivers for PHP for SQL Serverはこのドライバに基づいて構築されています。
sqlcmdとbcpユーティリティはこのドライバーで動作しますが、それぞれ別々にインストールされます。LinuxとmacOSではmssql-tools18パッケージ、WindowsではMicrosoftコマンドラインユーティリティです。
sqlcmdを使って Transact-SQL(T-SQL)文、システムプロシージャ、スクリプトファイルを実行します。
bcpを使って、SQL Serverのインスタンスとデータファイル間で、どちらの方向でも一括コピーを行います。
出発点を選択する
- ドライバーをインストールするには、WindowsのSystem Requirements、インストール、ドライバーファイルにアクセスするか、LinuxにODBCドライバーをインストールし、macOSにODBCドライバーをインストールし、unixODBCドライバーマネージャーをインストールしてください。
- 最初のアプリケーションを書くには、Connect toにアクセスしてC++やDSNと接続文字列のキーワードや属性を持つデータベースを検索してください。
- パスワードレス認証でAzure SQLに接続するには、ODBCドライバーでMicrosoft Entra IDを使用します。
- 既存のアプリに一時的な障害に対する回復性を持たせるには、接続の回復性および高可用性とディザスター リカバリーを参照してください。
- バージョン17からアップグレードするには、「 メジャーバージョンの違い 」と「 接続暗号化のトラブルシューティング」をご覧ください。
- 接続やクエリの問題を診断するには、「 接続暗号化のトラブルシューティング 」と 「既知の問題(LinuxおよびmacOS)」をご覧ください。
Azure SQLの運用ベースライン
このスニペットは、運用環境向けのAzure SQL接続の開始点として使用します。 アプリケーション設定からサーバー名とデータベース名を読み込み、管理型IDで認証して接続文字列に秘密が現れないようにし、完全な証明書検証付きTabular Data Stream(TDS)8.0暗号化を有効にします。 ログイン試行ごとにタイムアウトを設定し、一時的な障害が発生した場合は、指数バックオフとジッターを使用して再試行します。
この記事のC++スニペットでは、簡潔にするためにinclude、handle allocation、loginghelperを省略しています。
std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
cs += L";Server=tcp:"; cs += server; cs += L",1433";
cs += L";Database="; cs += database;
cs += L";Authentication=ActiveDirectoryMsi"; // managed identity, no stored secret
cs += L";Encrypt=strict"; // TDS 8.0 with certificate validation
cs += L";ConnectRetryCount=3"; // idle connection resiliency, not initial connect
cs += L";ConnectRetryInterval=10";
return cs;
}
// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
switch (nativeError) {
case 615: case 926: case 4060: case 4221:
case 10928: case 10929: case 10936:
case 40197: case 40501: case 40613:
case 42108: case 42109:
case 49918: case 49919: case 49920:
case 40020: case 40143: case 40166: case 40540: // failover subcodes
case 64: case 233: case 258:
case 10053: case 10054: case 10060:
return true;
default:
return false;
}
}
// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
SQLRETURN rc = SQL_ERROR;
for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
// Set the per-attempt connect timeout through the connection attribute.
// This works on every driver version, so the sample doesn't depend on
// which connection string keywords a given release accepts.
SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);
rc = SQLDriverConnectW(hDbc, nullptr,
const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
if (SQL_SUCCEEDED(rc)) {
Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
return rc;
}
// Walks the diagnostic records and returns the first record that carries
// a real SQL Server error number. Microsoft Entra failures report several
// driver-specific records first, whose native error is 0.
SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
if (attempt == maxAttempts || !IsTransient(native)) return rc;
// Cap the backoff at 64 seconds. This also keeps the shift in range
// when a caller passes a large maxAttempts.
int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
Sleep(delayMs);
}
return rc;
}
ConnectRetryCount
ConnectRetryIntervalまた、アイドル接続のレジリエンシーを有効にし、アイドル中に切断された接続を透過的に復元します。 彼らは最初の接続を再試行しないため、このスニペットはアプリケーションレベルの再試行も実装しています。 両方持っておけ。
ODBCはリターンコードだけでなく SQLGetDiagRec を通じて診断を報告するため、再試行前に故障を分類してください。 認証や設定エラーが即座に失敗し、再試行予算を全消費することはありません。
この構成の各部分の詳細については、以下を参照してください。
Azure SQLの一時的エラーのカタログについては、一時的故障エラーコードを参照してください。
主要な機能
- クロスプラットフォーム:Windows、Linux、macOSで同じAPIを使います。
- Microsoft Entra ID認証:パスワードレス接続で、管理されたアイデンティティ、サービスプリンシパル、インタラクティブ、統合フローが利用できます。
- 厳密暗号化:TDS 8.0接続で、バージョン18以降の完全な証明書検証が可能。
- 常に暗号化:クライアント側で機密カラムを暗号化し、カスタムキーストアプロバイダーのサポート。
- 接続レジリエンス:アイドル中に切断された接続を透明に復元すること。
-
高可用性:
MultiSubnetFailoverによる可用性グループリスナーサポート。 - データ分類:分類された列の感度メタデータ。
- ベクターデータタイプ: ベクター タイプのネイティブサポート。
- 分散トランザクション:Microsoft 分散トランザクション コーディネーター(MSDTC)を通じたXAトランザクションサポート。
- 補助ツール: sqlcmd と bcp、別々にインストール。
概要
| [アーティクル] | 説明 |
|---|---|
| ODBC Driver for SQL Server のダウンロード | サポートされているすべてのドライバーバージョンのインストーラーとパッケージのダウンロードが3つのプラットフォームすべてで提供されています。 |
| C++でデータベースに接続しクエリを行います | 接続し、クエリを実行し、結果を読み取る完全なC++サンプルで、セットアップをエンドツーエンドで確認できます。 |
| サポート ライフサイクル | どのドライバーバージョンがまだサポートされているか、そしてそれぞれのサポート終了日がわかります。 |
| メジャー バージョンの違い | バージョン17からバージョン18に移行すると、暗号化のデフォルト変更から何が壊れるのか。 |
ドライバーをインストールする
| [アーティクル] | 説明 |
|---|---|
| システム要件、インストール、ドライバーファイル(Windows) | サポートされたWindowsバージョン、サイレントデプロイ用のインストーラーコマンドライン、各ドライバーファイルのディスク上の位置。 |
| システム要件(LinuxおよびmacOS) | どのLinuxディストリビューションやmacOSのリリースが各ドライバをサポートしているか、さらにSQL Serverの互換性も考慮しています。 |
| LinuxにODBCドライバーをインストールしてください | Alpine、Debian、Red Hat、SUSE、Ubuntu、Azure Linuxのパッケージマネージャーのステップに加え、オフラインインストールやドライバーファイルの位置管理も可能です。 |
| macOSにODBCドライバーをインストールしてください | macOSのホームブルータップとフォーミュラの手順、バージョン18、17、または13.1のインストール方法も含まれます。 |
| UnixODBCドライバーマネージャー(LinuxおよびmacOS)をインストールしてください。 | LinuxとmacOSでODBCドライバーを読み込むドライバーマネージャーUnixODBCをインストールしたりアップグレードしたりしてください。 |
構成と接続
| [アーティクル] | 説明 |
|---|---|
| DSN と接続文字列のキーワードと属性 | 接続文字列のキーワード、DSN エントリ、SQLSetConnectAttr 属性の完全なカタログ。各項目で使用可能な値も含みます。 |
| 接続文字列キーワードおよびデータソース名(LinuxおよびmacOS) | LinuxやmacOSで odbc.ini と odbcinst.ini どのようにDSNを定義するか、さらにそれらのプラットフォームに特有のTLSやTCPのkeep-alive設定についても教えてください。 |
| ODBCデータソース管理者DSN(Windows) | 接続文字列ではなく UI を使用してデータ ソースを構成する場合の、Windows の DSN ウィザード ページ上のすべてのオプション。 |
| ドライバー対応接続プーリング (Windows) | どの接続文字列キーワードや属性が接続を専用のプールに入れ、どれがリセットのために追加のラウンド トリップを必要とするのか。 |
認証とセキュリティ
| [アーティクル] | 説明 |
|---|---|
| ODBCドライバーでMicrosoft Entra IDを使います | マネージド ID やサービス プリンシパルからインタラクティブや統合まで、すべての Authentication キーワード値を、それぞれに必要な設定とともに紹介します。 |
| ODBCドライバーでAlways Encryptedを使いましょう | クライアントプロセスの機密カラムを暗号化し、ドライバーのAPI概要とその文書化された制限を守り、平文がサーバーに届かないようにします。 |
| データの分類 | サーバーが機密列に付けるセンシティブラベルを読み、アプリケーションが独自のデータ保護ポリシーを適用できるようにします。 |
| 統合認証(LinuxおよびmacOS)を使います | Kerberosを設定して、LinuxやmacOSクライアントがSQL ServerのログインではなくWindowsの認証情報で接続できるようにしてください。 |
高い可用性と回復性
| [アーティクル] | 説明 |
|---|---|
| 接続の回復性 | サーバーがアイドル中に接続を切断した際、どうやってConnectRetryCountConnectRetryInterval復旧し、復旧が不可能なときにドライバーが返すIMCxxエラーについても教えてください。 |
| 高可用性とディザスター リカバリー | 可用性グループのリスナーを通じて接続し、フェイルオーバーがサブネットのタイムアウトで停止しないように MultiSubnetFailover を使いましょう。 |
| 透過的なネットワークIP解決を使用 | レガシー TransparentNetworkIPResolution フォールバックが複数の IP アドレスに対する接続試行の順序をどのように決定するのか、そしてなぜ MultiSubnetFailover がそれに取って代わるのか。 |
データの処理
| [アーティクル] | 説明 |
|---|---|
| ベクトル データ型 | vector 型をバインド、送信、取得します。これには、そのネイティブの C 表現および一括コピーのサポートが含まれます。 |
| DTCでのXAトランザクションをご利用ください | SQL Serverを分散トランザクションに組み込み、Windows、Linux、macOSのMicrosoft 分散トランザクション コーディネーターを通じて活用できます。 |
| プログラミングガイドライン(LinuxおよびmacOS) | どのドライバーがLinuxやmacOSでサポートしているのか、どの機能をサポートしていないのか、また文字セットやOpenSSLの処理がWindowsとどう違うのか。 |
診断とトラブルシューティング
| [アーティクル] | 説明 |
|---|---|
| 接続暗号化のトラブルシューティング | バージョン18がデフォルトで暗号化しているため、証明書や暗号化エラーを修正してください。 |
| データアクセストレーシング(LinuxおよびmacOS) | ドライバートレースをオンにして、アプリケーションが実際に行う呼び出しを確認するためにログファイルを取得してください。 |
| 既知の問題点(LinuxおよびmacOS) | 確認された欠陥とその回避策。 サポートケースを提出する前に、こちらを確認してください。 |
| よくある質問(LinuxおよびmacOS) | LinuxやmacOSのドライバーについてよく出てくる質問への短い回答です。 |
リリースノートとバグ修正
| [アーティクル] | 説明 |
|---|---|
| Windows向けリリースノート | 各Windowsドライバーリリースには新機能、挙動の変更、修正が含まれています。 |
| LinuxおよびmacOS向けのリリースノート | LinuxおよびmacOSの各ドライバーリリースにおける新機能、挙動変更、修正。 |
| SQL Serverツールのリリースノート | LinuxおよびmacOSではドライバーとは別にインストールされる sqlcmd および bcp ユーティリティの変更点。 |
Reference
| [アーティクル] | 説明 |
|---|---|
| Windows上のODBCドライバー | Windowsでドライバーがサポートしている内容のバージョンごとの概要と、Windows専用記事の索引です。 |
| Windows上のODBCドライバーの特徴 | どのリリースがWindowsの各機能とそれに伴う挙動の変更を導入したか。 |
関連するコンテンツ
- ODBCプログラマーの参考文献:このドライバが実装するODBC API仕様で、ドライバとは別に文書化されています。
- SQL Server ネイティブクライアント機能:ドライバーの挙動はネイティブクライアントのコンテンツにのみ記載されています。 これらの記事は、OLE DBを記述する部分を除き、ODBCドライバfor SQL Serverに適用されます。
- BCPユーティリティ:ドライバーとは別にインストールされる一括コピーユーティリティ。
- SQLcmdユーティリティ:コマンドラインクエリユーティリティで、ドライバーとは別にインストールされます。
- ドライバー機能サポートマトリックス
- SQL Server ドライバーのブログ