mssql-pythonのインストールおよび接続問題のトラブルシューティング

この記事を使って、 mssql-python ドライバーのインストール、接続、コンテナ、継続的統合(CI)の問題を診断してください。

インストールの問題

pip install が失敗する、またはソースからビルドされる

症状：

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

考えられる原因と解決策:

  • あなたのプラットフォームに合った既製ホイールはありません

    • サポートされているPythonバージョン(3.10以降)とプラットフォームを使っているか確認してください。 互換性マトリックスについては サポートライフサイクル を参照してください。
    • インストール前にPIPをアップグレードしてください pip install --upgrade pip。
    • リピータブルなチーム環境では、 Repeatable deployments のロックワークフローや Container and local development のコンテナパターンを活用してローカルマシンドリフトを減らしましょう。

  • 仮想環境は未起動

    • まずは仮想環境を起動してください。 システムPythonへのインストールは権限エラーや競合を引き起こすことがあります。
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • 欠落しているLinuxシステムライブラリ
    • このドライバーはLinux上で複数のシステムライブラリを必要とします。 インストールするパッケージについてはプラットフォーム 固有の依存関係 を参照してください。

競合するドライバーのインストール

症状：

同じ環境で mssql-python と pyodbc をインストールした後にインポートエラーや予期せぬ動作に遭遇します。

Solution:

mssql-python そして pyodbc 共存できる。 もし競合が発生した場合は、クリーンな仮想環境を作りましょう。

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

接続に関する問題

サーバーに接続できません

症状：

OperationalError: [08001] (0) Client unable to establish connection

考えられる原因と解決策:

  • サーバーにアクセスできません

    • サーバー名とポートが正しいか確認してください。
    • ping <server>やネットワーク接続をtelnet <server> 1433で確認してください。
    • ファイアウォールがポート1433でのアウトバウンド接続を許可していることを確認してください。

  • SQL Serverが動いていません

    • SQL Serverサービスが起動されているか確認してください。
    • 名前付きインスタンスについては、SQL Serverブラウザサービスが実行されているか確認してください。

  • Azure SQL firewall rules

    • クライアントのIPアドレスをAzureポータルのAzure SQLファイアウォールルールに追加してください。
    • Azure SQL Managed Instanceの場合は、許可されたネットワークから接続していることを確認してください。

基本的なTCP接続のテスト:

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

ログインに失敗しました

症状：

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

考えられる原因と解決策:

  • 認証モードの不一致

    • FabricのAzure SQL Database、Azure SQL Managed Instance、SQLデータベースでは、Authentication=ActiveDirectoryDefaultのようなMicrosoft Entraモードを好む。
    • 意図的にSQL認証を使う場合は、サーバーが許可しているか、そしてそのエンドポイントの正しいログイン形式を使用しているかを確認してください。

  • 誤ったSQL認証情報

    • ユーザーIDとパスワードを確認してください。
    • Azure SQLには、完全なユーザーIDを<user_id>@<server>記載してください。

  • ユーザーはデータベースに存在しません

    • ユーザーが指定されたデータベースにアクセスできるか確認してください。
    • サインインがデータベースユーザーに割り当てられているか確認してください。

  • 認証が設定されていません

    • Microsoft Entra認証(推奨):Authentication=ActiveDirectoryDefault。
    • SQL認証を受け入れるはずのローカルSQL Serverインスタンスをトラブルシューティングした場合は、SQL Serverが混合モード認証を使用しているか確認してください。

接続タイムアウト

症状：

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

考えられる原因と解決策:

  • サーバーの応答が遅い

    • 接続タイムアウトを延長してください。
    conn = mssql_python.connect(connection_string, timeout=60)

  • ネットワーク待ち時間

    • サーバーへのネットワーク経路を確認してください。
    • より短いネットワークパスや仮想プライベートネットワーク(VPN)を考えてみてください。

  • 重負荷下のサーバー

    • オフピーク時間帯に接続するようにしましょう。
    • データベース管理者に連絡してください。

SSL 証明書エラー

症状：

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

ソリューション:

信頼できる証明書や 、コンテナおよびローカル開発のローカル開発パターンを好む。 TrustServerCertificate=yesは自分が管理するサーバーとのローカル開発にのみ使ってください。

自己署名証明書を使った開発およびテストの場合:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Caution

TrustServerCertificate=yes はローカル限定の代替手段です。 共有開発コンテナやCIパイプライン、本番展開には持ち込まないでください。 詳細については、「 暗号化と証明書」をご覧ください。

本番環境では、適切な証明書をインストールし、以下を使用してください:

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

コンテナおよびCIの問題

Linuxにおける欠落したシステムライブラリ

症状：

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

配布用に必要なシステムパッケージをインストールしてください:

Distribution インストール コマンド
UbuntuまたはDebian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
レッドハットまたはフェドラ sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Dockerfileの例については、 コンテナおよびローカル開発を参照してください。

インストール後のmacOS SSLエラー

症状：

macOSから接続すると、特にAppleシリコン上でSSL関連のエラーが発生します。

Solution:

HomebrewでOpenSSLをインストールし、リンカーフラグを設定します:

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

関連するコンテンツ

  • Last updated on