mssql-odbc ドライバー(プレビュー版)を使ってください

mssql-python 2つのネイティブODBCプロバイダーのいずれかを読み込みます:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc RustベースのODBCドライバー プレビュー, オプトイン

mssql-python-rs 0.4.0パッケージにはmssql-odbcプロバイダーが含まれています。

Note

本番ワークロードには msodbcsql18 を使用してください。 プレビュー プロバイダーにオプトインする前に、そのmssql-odbcを必ず確認してください。

Availability

ドライバーは mssql-python-rs パッケージ内に、CPython 3.10以降のバージョン用のビルド済みホイールとして出荷されます。

Platform Architectures
Windows x64;CPython 3.11以降のバージョンでのARM64
macOS universal2(x86_64およびarm64)、macOS 15以降のバージョン
Linux (glibc) x86_64とaarch64(manylinux_2_28 および manylinux_2_34)
Linux (musl) x86_64とaarch64(musllinux_1_2)

ドライバーを有効にする

mssql-pythonをインストールするとmssql-python-rsもインストールされ、mssql-odbcドライバーが入っています。

python -m pip install mssql-python

--no-depsやプライベートインデックスでインストールする場合は、明示的にmssql-python-rsをインストールしてください。

最初の接続を開く前にプロバイダーを選択してください。 次のいずれかの方法を使用します。

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

MSSQL_CONNECTION_STRING環境変数をアプリケーションの接続文字列に設定してください。 証明書の検証を有効のままにしてください(Encrypt=yes;TrustServerCertificate=no)。 詳細については、「接続文字列 および 暗号化および証明書」をご覧ください。

選択したプロバイダーで次の例を実行してみてください:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

例は 1 を出力します。

提供者選定は以下のルールに従います:

  • MSSQL_PYTHON_NATIVE_PROVIDER は、native_provider よりも優先されます。 属性を競合するプロバイダーに設定すると RuntimeWarning が出力されます。
  • ドライバーが読み込まれる前に、native_providerをNoneに設定してPython の設定をクリアしてください。 これは環境変数を消すものではありません。
  • 認識されていない提供者名は ValueErrorが発生します。 native_providerに無効な名前を割り当てると即座に例外が発生します; 無効な環境変数は接続時に例外が発生します。 ドライバーはデフォルトのプロバイダーにフォールバックしません。
  • ドライバーがネイティブ接続の試みを開始すると、その試みが失敗してもプロバイダーは固定されます。 プロバイダーを切り替えるためにPythonを再起動してください。 native_provider を別のプロバイダーに変更しても、RuntimeWarning が発生し、効果はありません。

この時点より前に接続文字列の検証エラーやプロバイダーパッケージの欠如が発生します。 これらのエラーを修正し、再起動せずに別のプロバイダーを選ぶことができます。

mssql_python.get_native_provider_info()に電話してプロバイダー名、選択方法、選択が固定されているかどうかを確認してください。

msodbcsql18に戻るには、アプリケーションからMSSQL_PYTHON_NATIVE_PROVIDERとすべてのnative_provider割り当てを削除し、Python を再起動します。

マルチサブネット フェールオーバーの既定値

Rustプロバイダーは、該当する伝送制御プロトコル(TCP)接続に対してデフォルトで MultiSubnetFailover を有効にしています。 順次接続試行を要求するには、MultiSubnetFailover=no を明示的に設定してください。 展開全体のデフォルトを変更するには、ネイティブドライバーが最初に使用される前に MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT を true または false に設定してください。 connection-stringキーワードはこのデフォルトを上書きします。

数値 SQL_COPT_SS_MULTISUBNET_FAILOVER 属性(1248)も接続前に設定するとキーワードを上書きします。

このドライバは、非TCPトランスポート、データベースミラーリング、SQL Serverブラウザの検出を必要とする名前付きインスタンス、または明示的なプロトコルやアドレスを省略したローカルWindows接続に対してはこのデフォルトを有効にしていません。 非TCP トランスポート、データベース ミラーリング、または SQL Server Browser の検出で MultiSubnetFailover を明示的に有効にすると、接続エラーが発生します。 詳細は 高可用性とフェイルオーバー をご覧ください。

サポートされる機能

以下の機能は、既知の問題がありますが、サポートされています。

Area 注記
接続ライフサイクル 接続、close()、with ブロック、ログイン タイムアウト、診断、現在のデータベースの変更などが可能です。 接続文字列の設定には、 ApplicationIntent、 MultiSubnetFailover、 IpAddressPreference、 PacketSize、 KeepAlive、 ConnectRetryCount / ConnectRetryInterval (アイドル接続の回復力)が含まれます。 ネイティブドライバーは、サーバー支援のドメインネームシステム(DNS)キャッシュや、サーバーがサポートしている場合の強化ルーティングもネゴシエートします。
Authentication SQL 認証 (UID / PWD)、Windows 認証 (Trusted_Connection=Yes、Windows では Security Support Provider Interface (SSPI)、Linux および macOS では Kerberos を使用)、および Microsoft Entra ID の対話型、統合、デバイス コード、サービス プリンシパル、マネージド ID、既定の資格情報、アクセス トークン。 Microsoft Entra IDのパスワード認証はサポートされていません。 詳細については、「既知の問題の」を参照してください。
トランスポート層セキュリティ (TLS) Encrypt、TrustServerCertificate、HostnameInCertificate、ServerCertificate。
クエリの実行 直接実行と準備済み実行、事前計画の再利用、qmark パラメーター、そして mssql-python が実行する pyformat 変換。
ODBCエスケープ構文 機能、日付/時刻、外部結合、グローバル一意識別子 (GUID)、LIKE ... {escape ...}、インターバル、{encrypt ...} エスケープ形式。
ストアド プロシージャ Transact-SQL(T-SQL)や位置指定の{call ...}構文でexecute()を通じて呼び出し、結果セットを読み、nextset()で進めます。
入力パラメーター スカラーパラメータ、SQL NULL、 setinputsizes()、そして通常/ストリーム混在パラメーター。
大きなパラメーター ラージ テキスト、バイナリ、拡張可能マークアップ言語 (XML)、およびユーザー定義型 (UDT) パラメータは、実行時のデータ ストリーミングをサポートします。
executemany() ODBC パラメーター配列によるバッチ処理 ストリーム値を含む行は行単位実行にフォールバックします。
行の取得 fetchone()、 fetchmany()、 fetchall()、イテレーション、 fetchval()、タイプ変換、そして大規模なテキスト/バイナリストリーミングなどです。
矢印の取得 arrow_batch()、 arrow()、および arrow_reader()。 pyarrow が必要です。
複数の結果セット nextset()パラメータ配列によって生成される結果も含まれます。
Transactions オートコミット、コミット、ロールバック、そしてリード非コミット、リードコミット、リピーダブルリード、シリアライザブル、スナップショット分離レベル。 オートコミットをオフにすると、接続コンテキストマネージャーは成功裏に終了時にコミットし、例外が発生した際にロールバックします。
クエリのタイムアウト カーソルを作成する前に、Connection.timeoutを秒単位で設定してください。 ステートメントがそのタイムアウトを超えると、ドライバーは OperationalError を送出します。 0 はタイムアウトなしを意味します。 ログインタイムアウトは connect(timeout=...) を使用して個別に設定してください。
コネクションプーリング 組み込みの mssql-python プール（再利用前の接続リセットを含む） 認証固有のプール分離については、 アイデンティティ分離を参照してください。
メタデータ API tables()、 columns()、 primaryKeys()、 foreignKeys()、 statistics()、 rowIdColumns()、 rowVerColumns()、 procedures()、および getTypeInfo()。
Encoding とコンバーター デフォルトのワイド文字エンコーディング、出力コンバータ、UTF-8やレガシーSQLソートIDコレーションを含む、コレーション対応の非Unicodeパラメータ。 カスタムのシングルバイト文字デコードはクライアントのコードページと一致しなければなりません。 詳細については、「既知の問題の」を参照してください。

Microsoft Entra IDの統合認証は、Windows上でサインインしている Windows アカウントを使用します。 LinuxおよびmacOSでは、Kerberosチケットを使ってテナントのActive Directory フェデレーション サービス (AD FS)(AD FS)エンドポイントに認証します。 前提条件については、Windows統合認証を参照してください。

arrow_reader()を閉じると、進行中のフェッチSQLCancelを中断します。 close call はキャンセルの片付けが終わるまで待つことになります。 詳細については、 Apache Arrowの統合を参照してください。

データの種類

ドライバーはxml、json、vectorの値をPython strオブジェクトとして返し、vectorはJavaScriptオブジェクト表記(JSON)配列で表現されます。 geometry、geography、hierarchyid などの共通言語ランタイム (CLR) 型を Python bytes オブジェクトとして返します。 詳細については、 データ型マッピング および 既知の問題をご覧ください。

既知の問題

msodbcsql18からワークロードを切り替える前に、これらの違いを確認してください。

Issue Details Workaround
Microsoft Entra ID パスワード認証 Authentication=ActiveDirectoryPasswordはサポートされていません。 この方法は多要素認証(MFA)の要件を満たしません。 SQL認証(UID / PWD)は影響を受けません。 サービスプリンシパル、マネージドアイデンティティ、アクセストークンなど、別のMicrosoft Entra IDメソッドを使いましょう。
attrs_before 設定 Microsoft Entra IDの認証モードやアプリケーションの意図は数値接続属性として設定できません。 AuthenticationとApplicationIntent接続文字列のキーワードを使いましょう。
接続操作タイムアウト SQL_ATTR_CONNECTION_TIMEOUT はキャンセル クリーンアップを制御します。 プール接続のリセット時にタイムアウトを適用しません。 リセット中にサーバーが応答を停止すると、接続リクエストはブロックされたままになることがあります。 プールされたリセット タイムアウトは利用できません。 ログイン用に connect(timeout=...)、明細用に Connection.timeout を設定してください。
マルチアドレスホスト msodbcsql18 デフォルトで透過ネットワークIP解決(TNIR)を有効にしています。 mssql-odbc はこれをサポートしていません。 mssql-python は、どちらのプロバイダーでも TransparentNetworkIPResolution 接続文字列キーワードを拒否します。 可用性グループリスナーやその他のマルチアドレスホストには MultiSubnetFailover=yes を使いましょう。 デフォルトについては、 マルチサブネットフェイルオーバーデフォルトを参照してください。
データの分類 センシティブ分類のメタデータは利用できず、 SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400)もサポートされていません。 クエリ sys.sensitivity_classifications。
fork() 接続後 Linuxでは、親プロセスの接続後にフォークされたプロセスは、新しい接続でもドライバーを使うとハングすることがあります。 プーリングを有効にしていると、親もハングする可能性があります。 (#566) spawnスタート方式を使い、各ワーカー内部で接続してください。
Linuxにおけるネイティブトレーシング ネイティブトレーシングを有効にすると、Pythonはプロセス終了時のドライバークリーンアップ中に異常終了することがあります。 Linux では MSSQL_TDS_TRACE を未設定のままにします。
未読の結果 カーソルを閉じたり別の文を実行したりすると、キャンセルするのではなく、残りの結果を読み取って破棄するため、時間がかかることがあります。 プリペアドステートメントのクリーンアップはステートメントのクエリタイムアウトを使用しますが、タイムアウトがゼロになるとそのクリーンアップは制限されなくなります。 例えば TOPで必要な行だけを取得し、カーソルを作成する前に Connection.timeout を設定しましょう。
カスタム狭文字のデコード ネイティブドライバーは、WindowsではWindowsのANSIコードページを、LinuxやmacOSではプロセスロケールのコードページをナローテキストに対して使用しています。 コードページと一致しない明示的なPythonでのデコードは、誤ったテキストやbytesのような不正な文字を生み出すことがあります。 デフォルトのワイド文字デコードを使用します: conn.setdecoding(mssql_python.SQL_CHAR)。
Connection.getinfo() 一部の能力値やパケットサイズに基づく制限は msodbcsql18と異なります。 SQL_USER_NAME 接続文字列 UIDではなく、データベースのプリンシパルを報告します。 報告された機能や制限がアプリケーションに関係する場合は、特定のサーバーメタデータをクエリしてください。
メモリ不足エラー 一部のドライバー割り当ての失敗は、MemoryErrorを送出する代わりにPythonプロセスを終了させることもあります。 (#484) 送信する値や取得する値のサイズを制限しましょう。
大きな値の読み取りパフォーマンス varchar(max)およびnvarchar(max)データのチャンクリードはmsodbcsql18よりも遅くなることがあります。 (#473) ワークロードをベンチマーク化します。

問題を報告

バグが発生した場合は、 msodbcsql18 で再現し、両方のプロバイダーで発生したかどうかを記録してください。 切り替え手順については「ドライバーを有効にする」を参照してください。

レポートにはmssql_python.get_native_provider_info()の出力、OSの情報、Pythonおよびドライバーのバージョン、そして失敗したT-SQLバッチとエラーメッセージを含めてください。

Windowsでは、Pythonを起動する前にPowerShellでこれらの変数を設定し、ネイティブドライバーの診断を収集してください。 mssql-odbcを選択して問題を再現してください:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE トレースを有効にし、MSSQL_TDS_TRACE_LEVEL ログレベルを選択し、MSSQL_TDS_TRACE_DIR 標準エラー出力ではなく、ネイティブ ODBC ドライバーのプロセスごとのトレースファイル用のディレクトリを選択します。 Rustのコンパニオンパッケージは、現在のディレクトリ内の mssql_python_logs 配下にもログファイルを作成します。

トレースにはT-SQLテキストやパラメーター値が含まれます。 抜粋を共有する前に機密データを伏せてください。 診断後、これらの変数を削除し、Pythonを再起動してトレーシングを無効にしてください。

関連するコンテンツ

  • 最終更新: