インストール#

簡潔に言うと、サポートされているシステム を使っている場合は、次のコマンドでインストールできます。

pip install --upgrade pip           # pip を 20.3 以上にアップグレードする
pip install "psycopg[binary]"

これで、始める準備ができた はずです。他のインストール方法については、続きを読み進めてください。

サポートされているシステム#

ここにドキュメントされている psycopg のバージョンは、以下の環境で 公式かつテスト済みで サポートされます。

  • Python: バージョン 3.7 から 3.11

    • Python 3.6 は psycopg 3.1 より前までサポートされていました

  • PostgreSQL: バージョン 10 から 15

  • OS: Linux、macOS、Windows

サポートされたシステムを検証するテストは Github workflows で実行されています。そこでテストされていないものはすべて公式にはサポートされません。これには、次のものが含まれます。

  • Conda などの非公式の Python ディストリビューション

  • PostgreSQL の代替実装

  • GitHub ワークフローで利用可能ではない macOS ハードウェアおよびリリース

サポートされていないシステムで使用した場合でも、動作するかもしれません (なぜなら、たとえば、データベースが PostgreSQL と同一のワイヤープロトコルを使用しているかもしれないため) が、正しい動作や快適な使い勝手は保証できません。

バイナリのインストール#

psycopg 3 を使用して開発を始める最も早い方法は、次のようにバイナリパッケージをインストールすることです。

pip install "psycopg[binary]"

これにより、必要なすべてのライブラリが同梱された自己完結のパッケージがインストールされます。最低でも pip 20.3 が必要ですpip install --upgrade pip を実行して事前にアップデートしてください。

上のパッケージはほとんどの状況で動作するはずです。ただし、いくつかの場合には 動作しません

プラットフォームがサポートされていない場合、ローカル インストール純粋な Python インストール に進んでください。

参考

psycopg 3 は上手くインストールできましたか? 素晴らしい! これで モジュールの基本的な使用方法 に進んで動作方法が学べます。

上記のメソッドが上手く動作しない場合は、読み進めて、他の方法で psycopg 3 をインストールする必要があります。

パッケージ間の違いについての詳しい情報は、pq モジュールの実装 を参照してください。

ローカル インストール#

「ローカル インストール」により、機能するメンテナンス可能なライブラリが得られます。ライブラリはスピードアップのための C モジュールを含み、ライブラリのシステム アップグレードが psycopg 3 でも使われているライブラリをアップグレードできるように、システム ライブラリ (libpq, libssl...) にリンクされます。これは psycopg を本番環境にインストールするための望ましい方法です。

ローカル インストールを実行するためには、いくつかの前提条件が必要です。

  • C コンパイラ。

  • Python development ヘッダ (たとえば、python3-dev パッケージ)。

  • PostgreSQL クライアント development ヘッダ (たとえば、libpq-dev パッケージ)。

  • pg_config プログラムが PATH で利用可能であること。

あなたは extension のビルドのトラブルシューティングが できなければいけません。たとえば、あなたはコンパイラのエラーメッセージを読んで理解できる必要があります。もしそれができないなら、この方法を試すのはやめて、代わりに binary-installation に従ってください。

ビルドの前提条件が満たされていれば、次のコマンドが実行できます。

pip install "psycopg[c]"

純粋な Python インストール#

単純に以下のコマンドでインストールした場合

pip install psycopg

extras に [c][binary] を指定しなければ、純粋な Python 実装が取得されます。これは特にデバッグやハックのためには便利ですが、操作するためには依然としてシステム上に libpq が必要です (ctypes 経由で動的にインポートされます)。

純粋な Python インストールを使用するためには、libpq がシステムにインストールされている必要があります。たとえば、Debian システムではおそらく以下のコマンドを実行する必要があります。

sudo apt install libpq5

注釈

libpq は、PostgreSQL コマンドラインクライアントの psql がデータベースに接続するために使用するクライアントライブラリです。ほとんどのシステムでは、psql をインストールすると依存関係として libpq もインストールされます。

この要件を満たせない場合は、binary-installation に従ってください。

コネクションプールのインストール#

Psycopg のコネクション プール は、異なるリリースサイクルを可能にするために、psycopg パッケージ自体とは独立して配布されています。

プールを使用するためには、pip install "psycopg[pool]" コマンドを実行して pool extra をインストールするか、psycopg_pool パッケージを別にインストールする必要があります。psycopg_pool を使用するとインストールするリリースをより詳細に指定できます。

依存関係の処理#

プロジェクトの依存関係を指定する必要がある場合 (たとえば、requirements.txtsetup.pypyproject.toml ファイルの依存関係として)、おそらく以下のいずれか1つを指定する必要があります。

  • プロジェクトがライブラリである場合、psycopg を依存関係として追加する。これにより、ライブラリが正しいインターフェイスを持つ psycopg パッケージをインストールし、ライブラリのエンドユーザーに特定の実装を選択できる可能性を残せます。

  • プロジェクトが最終的なアプリケーションである場合 (たとえば、サーバー上で実行されるサービスなど)、前提条件が満たされていることを確認した後 (たとえば、依存ライブラリとツールがホストマシンにインストールされていることなど)、psycopg[c] などの特定の実装を要求できます。

いずれの場合でも、requirement specifiers を利用することで、使用する psycopg のバージョンを指定できます。

特定の実装が使用されることを保証したい場合、PSYCOPG_IMPL 環境変数を指定できます。これにより、指定された実装が利用できない場合にライブラリのインポートが失敗するようになります。詳しくは pq モジュールの実装 参照してください。