インストール#
簡潔に言うと、サポートされているシステム を使っている場合は、次のコマンドでインストールできます。
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.txt
、setup.py
、pyproject.toml
ファイルの依存関係として)、おそらく以下のいずれか1つを指定する必要があります。
プロジェクトがライブラリである場合、
psycopg
を依存関係として追加する。これにより、ライブラリが正しいインターフェイスを持つpsycopg
パッケージをインストールし、ライブラリのエンドユーザーに特定の実装を選択できる可能性を残せます。
プロジェクトが最終的なアプリケーションである場合 (たとえば、サーバー上で実行されるサービスなど)、前提条件が満たされていることを確認した後 (たとえば、依存ライブラリとツールがホストマシンにインストールされていることなど)、
psycopg[c]
などの特定の実装を要求できます。
いずれの場合でも、requirement specifiers を利用することで、使用する psycopg のバージョンを指定できます。
特定の実装が使用されることを保証したい場合、PSYCOPG_IMPL
環境変数を指定できます。これにより、指定された実装が利用できない場合にライブラリのインポートが失敗するようになります。詳しくは pq モジュールの実装 参照してください。