mssql-python の接続文字列

mssql-pythonドライバーは、SQL Server、Azure SQL Database、Azure SQL Managed Instance、およびMicrosoft FabricのSQLデータベースに接続する際に、以下の接続文字列キーワードをサポートしています。

接続文字列の構文

接続文字列はセミコロンで分離されたキー-値ペアを使用します:

keyword1=value1;keyword2=value2;...

特殊文字(セミコロン、等号、または巻き括弧)を含む巻き巻きの値:

PWD={my;complex=password}

値に文字通りの閉じ括弧を含めるには、2つの閉じ括弧(}})を使用します。

PWD={password}}with}}brace}

基本的な接続例

以下の例は、さまざまな認証方法を使って接続する方法を示しています。 本番環境では可能な限りMicrosoft Entra認証を活用してください。 コードや接続文字列からパスワードを排除します。

SQL Server with Microsoft Entra認証(推奨)

この例ではActiveDirectoryDefaultを使い、複数の認証情報ソース(Azure CLI、環境変数、管理型アイデンティティ)を順番に試します。 パスワードはコードとして保存されません:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL認証付きSQL Server

ローカル開発時には、自分が管理するSQL Serverインスタンスに対してSQL認証のみを使いましょう。 認証情報は接続文字列に埋め込まれているため、ソースコードではなく環境変数や.envファイルに保管してください。

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL with Microsoft Entra authentication

Azure SQL Databaseの接続文字列はSQL Serverと同じです。 ActiveDirectoryDefaultローカル開発、コンテナ、Azureホスト環境でコード変更なしで動作します:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

キーワードの引数を活用してください

接続パラメータは、接続文字列の代わりに、または追加してキーワード引数として渡すことができます。 キーワードの引数は、接続文字列アセンブリの陥落ポイントを回避します。 @、;、{、}などの特殊文字を持つパスワードは、キーワード引数として渡される場合、カーリーブラッシュラップは不要です。

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

接続文字列アセンブリと比較してください。アセンブリでは@を含むパスワードをラップする必要があります:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

正規化後、ドライバはキーワード引数を接続文字列に統合します。 キーワードの引数が接続文字列内のパラメータと一致する場合、そのキーワード引数が優先され、接続文字列の値を上書きします。

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

以下の例は、接続文字列とキーワード引数を組み合わせたものです:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

接続文字列キーワード

サーバーとデータベース

接続の対象となるSQL Serverインスタンスとデータベースを指定します。

Authentication

SQL認証用の認証情報を提供するか、Microsoft Entra認証モードを指定すること。 パスワードレスのオプションについては、Microsoft Entra認証モードをご覧ください。

暗号化とセキュリティ

すべての接続はデフォルトで Encrypt=yes を使用します。 ほとんどのアプリケーションでは、デフォルトで十分です。 strictはSQL ServerインスタンスがTDS 8.0をサポートし、TLS 1.3が必要な場合にのみ使用してください。 TrustServerCertificate=yesは自己署名証明書を持つ開発環境でのみ使用してください。

高可用性とフェールオーバー

これらのキーワードは、常時稼働のグループ展開に適用されます。 ApplicationIntent=ReadOnly、読み取り負荷の高いワークロード(レポート、分析)をセカンダリプレプリカにルーティングし、プライマリの負荷を軽減するように設定してください。 可用性グループが複数のサブネットにまたがる場合に MultiSubnetFailover=yes 設定してください。

性能とネットワーク

デフォルトはほとんどのアプリケーションで動作します。 大量データ転送時には PacketSize を最大32767まで増やしてください。 接続がファイアウォールを越えたり、アイドル中のTCPセッションをドロップするロードバランサーを越えた場合 KeepAlive 設定してください。

予約キーワード

Microsoft Entra認証モード

Authenticationキーワードは以下の値をサポートします。 あなたの展開に合ったモードを選択してください:

再現可能なDocker、devcontainer、CI環境の設定については、 コンテナおよびローカル開発を参照してください。 この記事はPythonのランタイム選択を一元化し、共有環境でダイジェストピン留め画像の使い方を示しています。

例:DefaultAzureCredential

ActiveDirectoryDefaultAzure単位元DefaultAzureCredentialチェーンにマッピングされます。 まずローカル開発中にAzure CLIトークンを試し、その後Azureにデプロイされた際にマネージドIDを試します:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

例:デバイスコードフロー

ブラウザがない環境(SSHセッションやDockerコンテナなど)で動作する場合はデバイスコードフローを活用しましょう。 ドライバーは別のデバイスでURLと入力コードを表示します:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

例:サービスプリンシパル

サービスプリンシパル認証は、クライアントIDとシークレットを持つ登録されたアプリケーションIDを使用します。 このアプローチは、ユーザー操作なしで動作するCI/CDパイプラインおよびバックグラウンドサービスに適用してください:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

アプリケーションを登録しデータベースアクセスを許可するには、Microsoft Entra service principals with Azure SQL を参照してください。 mssql-pythonの完全なセットアップについては、サービスプリンシパル認証を参照してください。

接続タイムアウト

接続タイムアウトは timeout パラメータで設定します。 サーバーにアクセスできないときにアプリケーションが無期限にハングしないようにタイムアウトを設けましょう:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

既存の接続のタイムアウトも変更できます:

conn.timeout = 60

自動コミット モード

デフォルトでは autocommit は Falseであり、これには明示的な commit() 呼び出しが必要です。 トランザクション制御を必要としないDDL文や読み取り専用クエリに対してオートコミットを有効にしてください:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

接続属性

接続が確立される前に、ODBC接続属性を設定するには以下の attrs_beforeを用います。

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

プログラム的接続文字列構築

接続文字列の注入を防ぐために、ユーザー入力時に文字列連結やf文字列は使わないでください。 代わりにキーワードの引数や環境変数を使いましょう。 JSON/YAML設定ファイル、Azure Key Vault、ビルダークラスなどの構築パターンについては、「Build connection strings by programmematics」を参照してください。

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

接続文字列の検証

ドライバーは接続文字列を検証し、未知またはスペルミスのあるキーワードに対して ConnectionStringParseError を上げます:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

関連するコンテンツ

• 接続文字列をプログラム的に構築する
• mssql-pythonをインストールする
• Microsoft Entra 認証
• 接続プール
• 接続管理