Show HN: Pglayers – スタック可能なDockerレイヤーとしてのPostgreSQL拡張機能
Show HN: Pglayers – PostgreSQL extensions as stackable Docker layers (github.com)
要約
Pglayersは、PostgreSQLの公式Dockerイメージに拡張機能を簡単に追加できるようにするツールです。通常、PostgreSQLの拡張機能は手動でのインストールやコンパイルが必要ですが、Pglayersは各拡張機能を最小限のDockerイメージレイヤーとして提供し、`COPY --from`コマンドで既存のPostgreSQLイメージに積み重ねるだけで利用できます。これにより、PostGIS、pgvector、pg_cronなどの多様な拡張機能を簡単にカスタムイメージに追加し、開発およびテストプロセスを効率化できます。
全文翻訳
pglayers
公式PostgreSQL Dockerイメージには拡張機能が含まれていません。pgvector、PostGIS、pg_cronなどの拡張機能が必要な場合、依存関係を手動でインストールしたり、ソースからコンパイルしたり、あるいは固定された拡張機能セットをバンドルしたサードパーティ製イメージに落ち着いたりする必要がありました。
pglayersはこの問題を解決します。これは拡張機能がプリインストールされた、すぐに使えるPostgreSQLディストリビューションであり、独自のカスタムイメージをビルドするためのツールでもあります。公式postgres Dockerイメージをベースに、必要な拡張機能だけを正確に含めることができます。PostgreSQL拡張機能のビルド方法、依存関係のインストール、コンパイラのセットアップを理解する必要はありません。
各拡張機能は、バイナリのみを含む最小限のDockerイメージレイヤーとして公開されています。これらをCOPY --fromを使用して公式postgresイメージの上にスタックします。拡張機能ごとに1行で済み、コンパイルは不要です。
クイックスタート
オプション1:すぐに使えるイメージ
shared_preload_librariesが既に設定済みの、プリビルドされた統合イメージ:
# 全ての80以上の拡張機能
docker run -d -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-full:17
# Azure Database for PostgreSQL互換(30以上の拡張機能)
docker run -d -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-azure:17
利用可能なプロファイルは full と azure です。それぞれPG 17, 18, 19向けに公開されています。詳細およびカスタムプロファイルの作成方法については、プロファイルを参照してください。
azureプロファイルにはDocumentDBが含まれており、ポート10260でMongoDBワイヤプロトコル互換性を提供します。これはAzure DocumentDBの背後にあるのと同じエンジンです。
注意: ベンダープロファイル(例:
azure)は、ローカル開発のためのベストエフォートによる近似です。実際のマネージドサービスを置き換えるものではありません。拡張機能のバージョン、デフォルト設定、プラットフォーム固有の動作が異なる場合があります。これらはローカルでの開発とテストに使用し、本番環境を正確に再現するために使用しないでください。
オプション2:自分で拡張機能を選択
各拡張機能は独自のイメージレイヤーとして公開されています。これらを公式postgresイメージにCOPY --fromでスタックします。各行が最終イメージに1つの拡張機能を追加します:
FROM postgres:17
COPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /
COPY --from=ghcr.io/pglayers/pgx-pg_cron:17 / /
COPY --from=ghcr.io/pglayers/pgx-postgis:17 / /
ビルドして実行します:
docker build -t my-postgres .
docker run -d -e POSTGRES_PASSWORD=secret my-postgres
コンパイルは発生しません。Dockerはレジストリからプリビルドされた拡張機能レイヤーをプルし、公式イメージの上にオーバーレイします。結果として、選択した拡張機能だけがレイヤーごとに構成された単一のイメージになります。
PG 18+ の分離レイアウト
PostgreSQL 18以降、pglayersはPostgreSQLのextension_control_path GUCを活用した分離拡張機能レイアウトを使用します。各拡張機能は独自の/extensions/<name>/名前空間に配置され、ファイル衝突のリスクを完全に排除します:
FROM postgres:18
COPY --from=ghcr.io/pglayers/pgx-pgvector:18 / /extensions/pgvector/
COPY --from=ghcr.io/pglayers/pgx-pg_cron:18 / /extensions/pg_cron/
COPY --from=ghcr.io/pglayers/pgx-postgis:18 / /extensions/postgis/
# PostgreSQLに分離された拡張機能の場所を伝える
RUN echo "extension_control_path = '/extensions/pgvector/share:/extensions/pg_cron/share:/extensions/postgis/share:$system'" \
>> /usr/share/postgresql/postgresql.conf.sample && \
echo "dynamic_library_path = '/extensions/pgvector/lib:/extensions/pg_cron/lib:/extensions/postgis/lib:$libdir'" \
>> /usr/share/postgresql/postgresql.conf.sample
リンカー設定(ld.so.conf.d/ldconfig/LD_LIBRARY_PATH)は不要です。各分離レイヤーは自己完結しています。出荷される各ELFオブジェクトは、自身の/extensions/<ext>/libを指す$ORIGIN RUNPATHを持ち、バンドルされたランタイムライブラリ(例:libcurl -> libssh2)は、拡張機能ごとにマングリングされたsoname(pglx_<ext>_<soname>)を持ちます。これにより、各レイヤーの依存関係はプライベートに保たれ、同じライブラリをバンドルする2つの拡張機能(例:postgisとpg_duckdbはどちらもlibssh2をlibcurl経由でプルする)が、共有Postgresプロセス内の互いのコピーにバインドされることを防ぎます。グローバルリンカーパスを設定すると、すべてのsonameが単一の勝者に収束し、そのクロスレイヤー衝突が再導入されます。
$systemと$libdirのサフィックスは、組み込みのcontrib拡張機能(hstore、pg_stat_statementsなど)が引き続き検出可能であることを保証します。
注意: プリビルドされたプロファイルイメージ(
pglayers-full:18、pglayers-azure:18)は、すべてのGUCおよびリンカー設定を自動的に処理します。手動設定は、オプション2で独自のイメージを構成する場合にのみ必要です。
Docker初心者の方へ: コンテナの検証方法については、コンテナの検証を参照してください。実行中の確認方法やポート競合の処理方法が説明されています。
サポートされているPostgreSQLバージョン
| バージョン | ステータス |
|---|---|
| PostgreSQL 17 | 安定版 |
| PostgreSQL 18 | 安定版 |
| PostgreSQL 19 | 実験的(ベータ4 -- 公式リリースまでサポート) |
全ての拡張機能はPG 17および18でビルドおよびテストされています。PG 19のサポートは、ベータ版である間はベストエフォートで行われます。一部の拡張機能はまだアップストリームとの互換性がない場合があります。PG 19がGAに達すると、安定版に昇格されます。
利用可能な拡張機能
| 拡張機能 | バージョン | PGバージョン | 説明 |
|---|---|---|---|
| age | 1.7.0 (PG17), 1.8.0 (PG18) | 17, 18 | オープンCypherクエリ言語を備えたグラフデータベース(Apache AGE) |
| anon | 3.1.1 | 17, 18 | データ匿名化およびマスキング |
| credcheck | 5.0 | 17, 18, 19 | ユーザー作成/パスワード変更時の認証情報チェック |
| db2fce | 0.0.17 | 17, 18 | DB2互換関数(日付/時刻、文字列ヘルパー) |
| documentdb | 0.117-0 | 17, 18 | MongoDB互換ドキュメントデータベースエンジン(BSON型とCRUD API) |
| extra_window_functions | 1.0 | 17, 18, 19 | 追加ウィンドウ関数(ignore-nullsバリアント、nth-from-last) |
| first_last_agg | 0.1.4-4-gd63ea3b | 17, 18 | first()およびlast()集計関数 |
| h3-pg | 4.2.3 | 17, 18 | Uber H3六角形地理空間インデックス |
| hll | 2.21 | 17, 18, 19 | HyperLogLog確率的ユニークカウント |
| http | 1.7.2 | 17, 18, 19 | PostgreSQL用HTTPクライアント(SQLからのWebリクエスト) |
| hypopg | 1.4.3 | 17, 18, 19 | 仮説インデックスによる「もしも」分析 |
| icu_ext | 1.11.0 | 17, 18, 19 | ICU関数:Unicode名、転写、スペルアウト、照合 |
| ip4r | 2.4.3 | 17, 18, 19 | GiSTインデックス付きIPv4/IPv6範囲データ型 |
| jsquery | 1.2 | 17, 18 | GINインデックス付きJSONクエリ言語 |
| orafce | 4.16.7 | 17, 18, 19 | Oracle互換関数およびパッケージ |
| periods | 1.2.3 | 17, 18 | SQL:2016アプリケーション時間PERIODおよびシステムバージョン管理 |
| pg_background | 2.0.2 | 17, 18, 19 | バックグラウンドワーカープロセスでSQLを実行 |
| pg_csv | 1.0.2 | 17, 18, 19 | 集計結果行をCSVテキストに変換 |
| pg_dirtyread | 2.8 | 17, 18, 19 | 削除(バキュームされていない)タプルを読み取り、フォレンジック/リカバリに利用 |
| pg_pwhash | 1.0 | 17, 18, 19 | パスワードハッシュ(scrypt, argon2, yescrypt) |
| pg_show_plans | 2.1.8 | 17, 18, 19 | 現在実行中の全クエリの実行計画を表示 |
| pg_statviz | 1.1 | 17, 18, 19 | PostgreSQL統計情報の時系列スナップショットを可視化 |
| pgaudit | 17.1 | 17, 18 | 監査ログ(セッションおよびオブジェクトレベル) |
| pg_bigm | 1.2 | 17, 18 | 2-gram全文検索(CJK言語に最適) |
| pg_clickhouse | 0.10.0 | 17, 18 | PostgreSQLからClickHouseデータベースをクエリ(プッシュダウン対応FDW、正規表現プッシュダウンにはre2が必要) |
| pg_cron | 1.6.7 | 17, 18 | ジョブスケジューラ(データベース内での定期ジョブ) |
| pg_duckdb | 1.1.1 | 17, 18 | Postgresに埋め込まれたDuckDBカラムナ分析エンジン |
| pg_durable | 0.2.9 | 17, 18 | データベース内での耐久性のある実行(耐障害性ワークフロー) |
| pg_failover_slots | 1.2.1 | 17, 18 | フェイルオーバー用論理レプリケーションスロットマネージャー |
| pg_graphql | 1.6.1 | 17, 18 | PostgreSQL用GraphQLサポート |
| pg_hashids | 1.2.1 | 17, 18, 19 | 整数から短くユニークなハッシュIDを生成 |
| pg_hint_plan | 1.7.1 | 17, 18 | SQLコメント内のヒントを使用して実行計画を調整 |
| pg_ivm | 1.13 | 17, 18 | マテリアライズドビューの増分ビューメンテナンス |
| pg_jsonschema | 0.3.4 | 17, 18 | JSONスキーマ検証 |
| pg_lake | 3.4.1 | 17 | Icebergおよびデータレイクファイルアクセス(Parquet, CSV, JSON via DuckDB) |
| pg_net | 0.20.3 | 17, 18, 19 | 非同期ノンブロッキングHTTP/HTTPSリクエスト |
| pg_partman | 5.4.3 | 17, 18, 19 | 自動テーブルパーティション管理 |
| pg_permissions | 1.4.1 | 17, 18, 19 | オブジェクト権限を指定された状態と比較してレビューおよび監査 |
| pg_qualstats | 2.1.4 | 17, 18, 19 | WHERE句述語の統計情報コレクター |
| pg_re2 | 0.4.1 | 17, 18, 19 | RE2を使用したClickHouse互換正規表現関数 |
| pg_repack | 1.5.3 | 17, 18, 19 | ロック負荷の少ないオンラインテーブル再編成 |
| pg_roaringbitmap | 1.2.0 | 17, 18 | 高速なセット操作のためのRoaring Bitmapデータ型 |
| pg_rrule | 0.3.0 | 17, 18, 19 | iCalendar RRULE繰り返しタイプと発生展開 |
| pg_similarity | 1.0 | 17, 18 | 類似度関数(レーベンシュタイン、ジャロ・ウィンクラー、コサイン、ジャッカード) |
| pg_squeeze | 1.9.3 | 17, 18, 19 | ロック負荷の少ないテーブルから未使用スペースを削除 |
| pg_stat_monitor | 2.3.2 | 17, 18 | ヒストグラムとバケットを備えた拡張クエリ統計情報 |
| pg_textsearch | 1.3.1 | 17, 18 | BM25関連度ランク付き全文検索 |
| pg_uuidv7 | 1.7.0 | 17, 18, 19 | UUIDv7生成(時間順ソート可能な一意ID) |
| pg_wait_sampling | 1.1.11 | 17, 18, 19 | 待機イベントのサンプリングベース統計情報 |
| pgfincore | 1.4.0 | 17, 18, 19 | データファイルのOSページキャッシュを検査および管理 |
| pgjwt | master | 17, 18, 19 | JSON Web Token(JWT)生成および検証 |
| pglogical | 2.4.7 | 17, 18, 19 | パブリッシュ/サブスクライブモデルを使用した論理ストリーミングレプリケーション |
| pgmq | 1.12.0 | 17, 18, 19 | Postgres上の軽量メッセージキュー(AWS SQS/RSMQのようなもの) |
| pgnodemx | 2.0.1 | 17, 18 | ノードOS/cgroupメトリクスをSQLとして公開(コンテナ対応監視) |
| pgpcre | 0.20190509 | 17, 18, 19 | Perl互換正規表現(PCRE)型と関数 |
| pgrouting | 4.0.1 | 17, 18, 19 | PostGIS上の地理空間ルーティングおよびネットワーク分析 |
| pgsodium | 3.1.11 | 17, 18, 19 | libsodiumを使用した最新の暗号化 |
| pgsphere | 1.5.2 | 17, 18 | 球面データ型(点、円、多角形)天文学/地理用 |
| pgtap | 1.3.4 | 17, 18, 19 | PostgreSQL用単体テストフレームワーク |
| pgtt | 4.5 | 17, 18, 19 | Oracle風グローバル一時テーブル |
| pgvector | 0.8.5 | 17, 18, 19 | AI/埋め込み用のベクトル類似性検索 |
| pgvectorscale | 0.9.0 | 17, 18 | DiskANNによる高性能ベクトル検索(pgvectorを補完) |
| pljs | 1.0.5 | 17, 18 | JavaScript(QuickJS)手続き型言語 |
| plpgsql_check | 2.10.1 | 17, 18, 19 | PL/pgSQLリンターおよびバリデーター |
| plprofiler | 4.2.5 | 17, 18 | PL/pgSQL関数のパフォーマンスプロファイラ |
| plv8 | 3.2.4 | 17, 18 | JavaScript(V8)手続き型言語 |
| PostGIS | 3.6.4 | 17, 18, 19 | 地理空間拡張機能(ジオメトリ、地理、ラスター、MVT) |
| postgres_protobuf | 0.3.2 | 17, 18, 19 | Protocol Bufferサポート(クエリ、JSONへの変換/JSONからの変換) |
| prefix | 1.2.11 | 17, 18, 19 | 電話ルーティング検索用のプレフィックス範囲データ型 |
| prioritize | 1.0.4 | 17, 18 | バックエンドプロセスのOSスケジューリング優先度を取得/設定 |
| rational | 0.0.2 | 17, 18, 19 | 精密分数(有理数)算術 |
| rum | 1.3.15 | 17, 18 | GINライクなインデックスで全文検索の順序付けが可能 |
| semver | 0.41.0 | 17, 18, 19 | セマンティックバージョンデータ型 |
| set_user | 4.2.0 | 17, 18, 19 | 監査可能な権限昇格制御(set_user/reset_user) |
| tdigest | 1.4.4 | 17, 18, 19 | T-digestによる分位数およびパーセンタイル推定 |
| tds_fdw | 2.0.5 | 17, 18 | SQL ServerおよびSybase用外部データラッパー |
| temporal_tables | 1.2.2 | 17, 18 | システム期間テンポラルテーブル |
| timescaledb | 2.28.2 | 17, 18 | 時系列ハイパーテーブル、圧縮、継続的集計 |
| timestamp9 | 1.4.0 | 17, 18, 19 | ナノ秒精度のタイムスタンプ型 |
| toastinfo | 1.7 | 17, 18, 19 | 値のTOASTストレージ詳細を検査 |
| wal2json | 2.6 | 17, 18 | 論理レプリケーション/CDC用のJSON出力プラグイン |
| wrappers | 0.6.2 | 17, 18 | 外部データラッパーフレームワーク(Stripe, S3, Firebaseなど) |
イメージタグ
各拡張機能は2つのタグ形式で公開されています:
pgx-<extension>:<pg_major>-- 最新ビルド(例:pgx-pgvector:17)pgx-<extension>:<pg_major>-<version>-- ピン留めされたバージョン(例:pgx-pgvector:17-v0.8.3)
全てのイメージはマルチアーキテクチャ(linux/amd64およびlinux/arm64)で、GHCRのghcr.io/pglayers/pgx-*でホストされています。Dockerは自動的にプラットフォームに合ったアーキテクチャをプルします。
設定に関する注意点
shared_preload_libraries
一部の拡張機能は、shared_preload_librariesへのエントリが必要です。COPY行の後にDockerfileに追加してください:
RUN echo "shared_preload_libraries = 'pg_cron,pgaudit,pg_partman_bgw'" \
>> /usr/share/postgresql/postgresql.conf.sample
これが必要な拡張機能:
| 拡張機能 | ライブラリ名 |
|---|---|
| age | age |
| anon | anon |
| credcheck | credcheck |
| documentdb | pg_documentdb_gw_host |
| pg_cron | pg_cron |
| pg_duckdb | pg_duckdb |
| pg_durable | pg_durable |
| pg_failover_slots | pg_failover_slots |
| pg_hint_plan | pg_hint_plan |
| pg_lake | pg_extension_base |
| pg_net | pg_net |
| pg_partman | pg_partman_bgw |
| pg_qualstats | pg_qualstats |
| pg_show_plans | pg_show_plans |
| pg_squeeze | pg_squeeze |
| pg_stat_monitor | pg_stat_monitor |
| pg_textsearch | pg_textsearch |
| pg_wait_sampling | pg_wait_sampling |
| pgaudit | pgaudit |
| pglogical | pglogical |
| pgnodemx | pgnodemx |
| pgsodium | pgsodium |
| pgtt | pgtt |
| plprofiler | plprofiler |
| set_user | set_user |
| timescaledb | timescaledb |
CREATE EXTENSION
拡張機能は、使用したい各データベースで作成する必要があります。initスクリプトでこれを自動化できます:
COPY <<'EOF' /docker-entrypoint-initdb.d/10-extensions.sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS postgis;
EOF
これは、コンテナが最初に起動したとき(データディレクトリが初期化されたとき)に自動的に実行されます。
PostGIS
PostGIS拡張機能イメージは、そのランタイム共有ライブラリ(libgeos, libproj, libgdal, libjson-c, libprotobuf-c、およびPROJ/GDALデータファイル)をバンドルしているため、COPY --fromは完全に自己完結しています。ジオメトリ、地理、トポロジー、ラスター、MVT(Mapbox Vector Tiles)がすべて含まれています。
GDALラスターフォーマットドライバー(GeoTIFF, PNGなど)を有効にするには、環境変数を設定します:
ENV POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL
デフォルトでは、セキュリティ上の理由からGDALドライバーは無効になっています(公式PostGIS Dockerイメージと同じ)。
DocumentDB
DocumentDBは、PostgreSQL上に構築されたMongoDB互換のドキュメントデータベースエンジンを提供します。これは2つの拡張機能で構成されます:
documentdb_core-- BSONデータ型とコア操作(依存関係なし、スタンドアロンで動作)。documentdb-- 完全なCRUD APIサーフェス。documentdb_core、pg_cron、vector(pgvector)、postgis、tsm_system_rows、およびdocumentdb_extended_rumが必要です。
レイヤーには、ポート10260でMongoDBワイヤプロトコル互換性を提供するバックグラウンドワーカーpg_documentdb_gw_hostも含まれています。shared_preload_librariesを介してロードされると、MongoDBクライアント(mongosh, pymongo, Node.jsドライバー)が直接接続できます。
拡張機能を順番に作成します:
CREATE EXTENSION IF NOT EXISTS documentdb_core;
-- 完全なAPIの場合(pg_cron, vector, postgisレイヤーが必要):
CREATE EXTENSION IF NOT EXISTS documentdb;
CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum;
DocumentDB 0.117は、デフォルトでインデックス操作にExtended RUMを必要とします。CREATE EXTENSION documentdb CASCADEはdocumentdb_extended_rumを作成しないため、別途作成する必要があります。
ゲートウェイ設定(postgresql.confに追加):
shared_preload_libraries = 'pg_cron,pg_documentdb_core,pg_documentdb,pg_documentdb_extended_rum,pg_documentdb_gw_host'
documentdb_gateway.database = 'postgres'
documentdb_gateway.setup_configuration_file = '/etc/documentdb/gateway_config.json'
デフォルトの設定ファイルは、/etc/documentdb/gateway_config.jsonにレイヤーとしてバンドルされています。これはポート10260でリッスンし、自動生成された自己署名TLS証明書を使用します(クライアントはTLSあり/なしで接続できます)。ポート、TLS、またはブロックされたロールをカスタマイズするには、独自のファイルで上書きしてください。
PG 18+ の分離レイアウトでは、バンドルされた設定は
/extensions/documentdb/etc/documentdb/gateway_config.jsonにあります。統合プロファイルイメージは、ゲートウェイが正常に機能するように、そこに/etc/documentdb/gateway_config.jsonのシンボリックリンクを追加します。これらのプロファイルイメージでは、documentdbとdocumentdb_extended_rumも最初の初期化時に自動作成されます(プロファイルイメージ参照)。そのため、ゲートウェイは「拡張機能がまだ作成されていない」というリトライなしで起動します。PGLAYERS_CREATE_EXTENSIONS=noneを設定してオプトアウトできます。
pg_lake
pg_lakeは、PostgreSQLにIcebergテーブルサポートとデータレイクファイルアクセス(Parquet, CSV, JSON)を提供します。DuckDBをクエリエンジンとして、コンパニオンプロセスを介して使用します。
レイヤーに含まれるもの:
- 複数のPostgreSQL拡張機能(
pg_lake、pg_lake_table、pg_lake_engine、pg_lake_iceberg、pg_lake_copy、pg_extension_base、pg_map) pgduck_serverバイナリ(スタンドアロンDuckDBベースプロセス)- 自動起動エントリポイントラッパー
セットアップ:
FROM postgres:17
COPY --from=ghcr.io/pglayers/pgx-pg_lake:17 / /
RUN echo "shared_preload_libraries = 'pg_extension_base'" \
>> /usr/share/postgresql/postgresql.conf.sample
ENTRYPOINT ["/usr/local/bin/pg-lake-entrypoint.sh"]
CMD ["postgres"]
エントリポイントラッパーは、pgduck_serverをバックグラウンドで起動します(Unixソケット、ポート5332、外部ポートは公開されません)。その後、標準のPostgresエントリポイントに委譲します。手動でのプロセス管理は不要です。
CREATE EXTENSION pg_lake CASCADE;
注意: pg_lakeはpg_duckdbと競合します(どちらもlibduckdb.soをバンドルしています)。同じイメージで両方使用しないでください。
PostgreSQL 17のみ。 pg_lakeは、shared_preload_librariesにpg_extension_baseシムが必要です。このシムは、すべてのCREATE EXTENSIONをインターセプトし、ハードコードされた$system sharedirでターゲットのコントロールファイルを探し、PostgreSQL 18のextension_control_pathを無視するProcessUtilityフックをインストールします。PG 18+の分離レイアウトは、すべての拡張機能を/extensions/<ext>/shareの下にインストールし、extension_control_pathのみで解決するため、pg_extension_baseをプリロードすると、イメージ内のすべての拡張機能(およびpg_lake自体)のCREATE EXTENSIONが壊れます。したがって、pg_lakeはアップストリームがpg_extension_baseにextension_control_pathを尊重させるようになるまで、PG 17クラシックレイアウト向けにのみビルドされます。詳細については、issue #37およびアップストリームのSnowflake-Labs/pg_lake#494を参照してください。
プロファイルイメージ(自動設定)
プリビルドされた統合イメージ(pglayers-full、pglayers-azure)は、すべてのランタイム設定を自動的に処理します:
-
shared_preload_libraries-- 各拡張機能のSHARED_PRELOADフィールドから設定されます。 -
max_worker_processes--64に引き上げられます(デフォルトの8は、多数のバックグラウンドワーカー拡張機能がプリロードされると低すぎ、too many background workersエラーやTimescaleDBランチャーの再試行ループの原因となります)。 -
postgresql.conf設定 -- 拡張機能に必要なGUCパラメータ(例:
documentdb_gateway.database)は、各拡張機能のPG_CONFフィールドから自動的に追加されます。これには、pgnodemx.kdapi_enabled = off(k8s外ではKubernetes Downward APIなし)やcron.log_statement = off(スケジュールされたジョブをサーバーログにエコーしない)のようなノイズ抑制デフォルトが含まれます。 -
コンパニオンプロセス -- バックグラウンドプロセスを必要とする拡張機能(例:pg_lakeの
pgduck_server)は、生成されたエントリポイントラッパーを介して自動的に起動されます。手動でのプロセス管理は不要です。 -
自動作成拡張機能 -- 常にオンのバックグラウンドワーカーまたはワイヤプロトコルゲートウェイを備え、SQLオブジェクトをポーリングする拡張機能(現在 documentdb)は、最初の初期化時に
CREATE EXTENSION ... CASCADEを介して自動的に作成されるため、新しいコンテナは永続的な「まだ作成されていない」警告なしに起動します。PGLAYERS_CREATE_EXTENSIONS環境変数(SQL拡張機能名のスペース/カンマ区切りリスト、または無効にする場合はnone)でオーバーライドできます:# 自動作成を完全に無効にする docker run -e PGLAYERS_CREATE_EXTENSIONS=none ghcr.io/pglayers/pglayers-full:18 # 別のセットを自動作成する docker run -e PGLAYERS_CREATE_EXTENSIONS="vector,postgis" ghcr.io/pglayers/pglayers-full:18
プロファイルイメージを使用する場合、上記のいずれも手動で設定する必要はありません。docker runしてCREATE EXTENSIONするだけです。
仕組み
このプロジェクトは、PostgreSQLバージョンごとに1つのDockerイメージを拡張機能ごとに公開します。これらは実行可能なコンテナではなく、拡張機能のアーティファクトのみを含むFROM scratchイメージです。
以下のように記述した場合:
COPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /
Dockerは、拡張機能ファイルを公式postgresイメージの正しいパス(/usr/lib/postgresql/17/lib/、/usr/share/postgresql/17/extension/)にコピーします。PostgreSQLはそれらを見つけ、CREATE EXTENSIONを実行できます。コンパイル、パッケージマネージャー、ランタイム依存関係の解決は不要です。公式イメージの上にファイルコピーを積み重ねるだけです。
拡張機能のビルド方法
拡張機能は、4つのビルドファミリーに分類されます(優先順位順):
- APT(共有テンプレート経由) -- ほとんどの拡張機能のデフォルトです。Dockerfileは一切ありません。単一の共有
Dockerfile.aptがPGDGからpostgresql-<pg>-<pkg>をインストールし、ファイルを抽出し、ベース以外のランタイムライブラリをバンドルし、クラシックレイアウト用に再配置します。extension.conf(APT_PACKAGE付き)とtest.sqlのみを記述します。(約56拡張機能、例:pgvector, pg_cron。) - APT(カスタムDockerfile付き) -- 共有テンプレートで表現できないAPTパッケージの場合:複数の/名前変更されたパッケージ、
.controlのupdate-alternativesシンボリックリンク、または追加の手順。(例:postgis, pgrouting, http, h3_pg, tds_fdw。) - ソースビルド(アップストリームプリビルドイメージから) -- 公式イメージまたはキャッシュされたビルドステージを出荷する重いビルドの場合、CIでの長いコンパイル時間を回避します。(例:
pgduckdb/pgduckdbからのpg_duckdb、プリビルドされたvcpkgイメージからのpg_lake。) - ソースビルド(gitから) -- APTパッケージが存在しない場合、ピン留めされたアップストリームタグで
git clone+make。(例:pg_net, pgsodium, pgrx/Rust拡張機能。)
どのファミリーであっても、各レイヤーは自己完結(ベース以外のすべてのランタイムライブラリを自身で持つ)し、衝突がないこと。これはテストスイートによって強制されます。ビルド要件についてはAGENTS.mdを、追加方法についてはCONTRIBUTING.mdを参照してください。
PG 17:クラシックレイアウト
拡張機能ファイルは、標準のPostgreSQLファイルシステムパスに配置されます:
/usr/lib/postgresql/17/lib/vector.so
/usr/share/postgresql/17/extension/vector.control
/usr/share/postgresql/17/extension/vector--0.8.4.sql
DockerfileでCOPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /と記述すると、Dockerはこれらのファイルを公式postgresイメージの正しい場所にコピーします。PostgreSQLはそれらを見つけ、CREATE EXTENSIONを実行できます。
PG 18+:分離レイアウト
拡張機能ファイルは、PostgreSQLのextension_control_path GUCおよびCloudNativePG ImageVolumesと互換性のあるフラットレイアウトを使用します:
/lib/vector.so
/lib/bitcode/vector/...
/share/extension/vector.control
/share/extension/vector--0.8.4.sql
各拡張機能イメージは、統合イメージ内の独自の名前空間(/extensions/<name>/)にマウントされます。PostgreSQLはextension_control_pathおよびdynamic_library_path GUCを介してそれらを発見します。このアプローチは:
- ファイル衝突を排除 -- 2つの拡張機能が同じライブラリの異なるバージョンをバンドルしても競合しません。
- ランタイムコンポーザビリティを可能に -- デプロイ時にDockerボリュームまたはKubernetes ImageVolumesを介して拡張機能をマウントできます。
- CNPGネイティブ -- pglayers
:18イメージは、変更なしでCloudNativePGClusterImageCatalogエントリとして直接使用できます。
CloudNativePGの使用
pglayers PG 18+イメージは、CloudNativePG ImageVolume拡張機能と直接互換性があります(CNPG >= 1.27およびKubernetes >= 1.33が必要です)。
重要:OS互換性。 pglayers拡張機能は
postgres:18(Debian Trixie、glibc 2.38)に対してビルドされています。CNPGを使用する場合、オペランドイメージもTrixieベースである必要があります:imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixieBullseye/Bookwormバリアント(
ghcr.io/cloudnative-pg/postgresql:18)は古いglibcを持っており、GLIBC_2.38 not foundで失敗します。これはCNPG自身の拡張機能イメージにも適用される制約です。拡張機能はオペランドのOSディストリビューションと一致する必要があります。
クラスター用のClusterImageCatalogを生成します:
make cnpg-catalog PG=18 REGISTRY=ghcr.io/pglayers > catalog.yaml
kubectl apply -f catalog.yaml
または特定のプロファイルの場合:
make cnpg-catalog PG=18 PROFILE=azure REGISTRY=ghcr.io/pglayers > catalog-azure.yaml
次に、CNPG Cluster仕様で拡張機能を参照します:
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: my-cluster
spec:
instances: 3
imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie
imageCatalogRef:
apiGroup: postgresql.cnpg.io
kind: ClusterImageCatalog
name: pglayers
major: 18
postgresql:
shared_preload_libraries:
- pg_cron
extensions:
- name: pgvector
- name: pg-cron
- name: postgis
ld_library_path:
- lib
カタログなしで拡張機能を直接定義することもできます:
postgresql:
extensions:
- name: pgvector
image:
reference: ghcr.io/pglayers/pgx-pgvector:18-0.8.4
- name: postgis
image:
reference: ghcr.io/pglayers/pgx-postgis:18-3.6.4
ld_library_path:
- lib
ランタイム依存関係をバンドルした拡張機能(PostGIS、pgRouting)は、共有ライブラリを/extensions/<name>/lib/で見つけられるようにld_library_path: ["lib"]が必要です。
Kubernetes ImageVolumes(CNPGなし)
pglayers拡張機能イメージは、標準のpostgres:18イメージと組み合わせてKubernetes ImageVolumesとしても機能します。オペレーターは不要です。これにより、Kubernetes 1.33+クラスターでランタイム拡張機能のコンポジションが可能になります:
apiVersion: v1
kind: Pod
metadata:
name: postgres-with-extensions
spec:
volumes:
- name: ext-pgvector
image:
reference: ghcr.io/pglayers/pgx-pgvector:18-0.8.4
- name: ext-postgis
image:
reference: ghcr.io/pglayers/pgx-postgis:18-3.6.4
- name: ext-pg-cron
image:
reference: ghcr.io/pglayers/pgx-pg_cron:18-v1.6.7
containers:
- name: postgres
image: postgres:18
env:
- name: POSTGRES_PASSWORD
value: "secret"
args:
- "postgres"
- "-c"
- "extension_control_path=/extensions/pgvector/share:/extensions/pg_cron/share:/extensions/postgis/share:$$system"
- "-c"
- "dynamic_library_path=/extensions/pgvector/lib:/extensions/pg_cron/lib:/extensions/postgis/lib:$$libdir"
- "-c"
- "shared_preload_libraries=pg_cron"
volumeMounts:
- name: ext-pgvector
mountPath: /extensions/pgvector
readOnly: true
- name: ext-postgis
mountPath: /extensions/postgis
readOnly: true
- name: ext-pg-cron
mountPath: /extensions/pg_cron
readOnly: true
各拡張機能イメージは、/extensions/<name>/に読み取り専用ボリュームとしてマウントされます。PostgreSQLはextension_control_pathおよびdynamic_library_pathを介してそれらを発見します。イメージの再ビルドは不要です。ボリューム定義を変更するだけで、拡張機能を追加または削除できます。
要件: Kubernetes 1.33+(ImageVolume GA)。
$$systemおよび$$libdirサフィックスは、組み込みのcontrib拡張機能が利用可能であることを保証します。
OCIイメージラベル
すべての拡張機能イメージには、機械可読な検出のための標準的なOCIラベルが含まれています:
| ラベル | 説明 |
|---|---|
org.opencontainers.image.title | 拡張機能名 |
org.opencontainers.image.description | 短い説明 |
org.opencontainers.image.version | 拡張機能バージョン |
org.opencontainers.image.source | アップストリームリポジトリURL |
org.opencontainers.image.licenses | SPDXライセンス識別子 |
io.pglayers.pg.major | PostgreSQLメジャーバージョン |
io.pglayers.layout | classicまたはisolated |
io.pglayers.extension.name | 拡張機能名 |
io.pglayers.extension.version | 拡張機能バージョン |
ラベルは以下でクエリできます:
docker inspect ghcr.io/pglayers/pgx-pgvector:18 --format '{{json .Config.Labels}}'
ローカルビルド
前提条件
- Docker(BuildKit付き)
- GNU Make
- Bash
ビルドコマンド
# 利用可能な拡張機能の説明とPGバージョンを表示
make list
# 特定のPGバージョン向けに単一拡張機能をビルド
make build EXT=pgvector PG=17
# PGバージョン向けの全拡張機能をビルド
make build-all PG=17
# PG 19向けにビルド(現在のプレリリースタグが自動的に解決されます)
make build EXT=pgvector PG=19
make build-all PG=19
# 全ての拡張機能を含む統合イメージをビルド
make image PG=17 REGISTRY=local
# カスタムイメージ名
make image PG=18 REGISTRY=local IMAGE_NAME=my-postgres
# 拡張機能の詳細情報を表示(バージョン、注意点、プリロード要件)
make info EXT=pg_cron
# ビルドされた拡張機能イメージをレジストリにプッシュ
make push EXT=pgvector PG=17
# 全ての拡張機能をプッシュ
make push-all PG=17
# デフォルトレジストリをオーバーライド
make build EXT=pgvector PG=17 REGISTRY=ghcr.io/myorg
# 拡張機能のDockerfileを表示(デバッグに便利)
make dockerfile EXT=pgvector
# 単一拡張機能のビルド済みイメージを削除
make clean EXT=pgvector
# 全ての拡張機能イメージを削除(ディスクスペースを解放)
make clean-all
# 新しいAPTベース拡張機能をスキャフォールディング(PGDGをプローブし、ライセンスを検出し、extension.conf + test.sqlスタブを作成)
make add-apt-ext PKG=<apt-package> [NAME=<dir>] [PG=17]
# 全ての拡張機能がライセンスポリシーに準拠しているか検証
make check-licenses
# プロファイルがextensions/ディレクトリと同期しているか検証
make check-profiles
APTベースの拡張機能にはDockerfileはありません。共有の
Dockerfile.aptによってビルドされ、バージョンとPostgreSQLバージョンサポートはビルド時にPGDGから解決されます。追加するのは通常make add-apt-ext+test.sqlの記述だけです。コントリビューティングガイドを参照してください。
CIでの拡張機能のスキップ
extension.confにCI_SKIP=1を持つ拡張機能は、CIビルドから除外されますが、リポジトリにはローカルビルド用に残ります。これは、ビルド時間が非常に長い拡張機能(例:plv8。V8エンジンのコンパイルがarm64エミュレーションでのCIタイムアウトを超える)に便利です。
# ローカルでは引き続き動作
make build EXT=plv8 PG=17
# しかしCIではスキップされる(ビルドマトリックス、プロファイルイメージに含まれない)
拡張機能をスキップするには、extension.confにCI_SKIP=1を追加します。再有効化するには、フィールドを削除し、拡張機能を適切なプロファイルに戻します。
テストの実行
# 完全なテストスイート:衝突、ldd、CREATE EXTENSION、スモークテスト、
# 統合テスト(まず全ての拡張機能をビルドします)
make test REGISTRY=local PG=17
# 既にビルドされた統合イメージに対するクイック統合テスト
make image PG=17 REGISTRY=local
make test-image PG=17
# Kubernetes ImageVolume統合テスト(k3d、PG 18+が必要)
make test-k8s REGISTRY=local PG=18
テストは、サポートされている全てのPGバージョン(17, 18, 19)でパスする必要があります。
プロファイル
プロファイルを使用すると、フルセットではなく、キュレーションされた拡張機能のサブセットをビルドおよびテストできます。これは、マネージドPostgreSQLサービス(例:Azure Database for PostgreSQL)の提供に合わせたり、目的特化型イメージを作成したりするのに役立ちます。
# 利用可能なプロファイルを表示
make list-profiles
# プロファイル内の拡張機能を表示
make list PROFILE=azure
# プロファイル内の拡張機能のみをビルド
make build-all PG=17 PROFILE=azure
# プロファイルの拡張機能のみを含む統合イメージをビルド
make image PG=17 PROFILE=azure # 生成されるもの: pglayers-azure:17
# プロファイルに対してフルテストスイートを実行
make test REGISTRY=local PG=17 PROFILE=azure
# 全てのプロファイルファイルがextensions/と同期しているか検証
make check-profiles
提供されるプロファイル
| プロファイル | 説明 |
|---|---|
full | pglayersが提供する全ての拡張機能 |
azure | Azure Database for PostgreSQL Flexible Serverに一致する拡張機能 |
カスタムプロファイルの作成
profiles/ディレクトリにテキストファイルを作成し、拡張機能ディレクトリ名を1行に1つずつ記述します(アルファベット順)。コメント(#)と空行は無視されます:
# カスタムプロファイル
pg_cron
pgvector
postgis
その後、使用します:
make image PG=17 PROFILE=myprofile
make test REGISTRY=local PG=17 PROFILE=myprofile
公開されているプロファイルイメージ
CIは統合プロファイルイメージをGHCRにビルドしてプッシュします:
ghcr.io/<owner>/pglayers-azure:17ghcr.io/<owner>/pglayers-azure:18ghcr.io/<owner>/pglayers-full:17ghcr.io/<owner>/pglayers-full:18
これらは、プロファイルの拡張機能がプリインストールされ、shared_preload_librariesが設定された、すぐに使えるPostgreSQLイメージです。
make testスイートは以下をチェックします:
-
ファイル衝突なし -- 各拡張機能のペアをファイル重複について比較します。2つの拡張機能が同じパスにファイルをインストールした場合、最後の
COPY --fromが静かに上書きします。Dockerはこれについて警告を一切出しませんが、実行時に拡張機能を破損させる可能性があります。 -
ベースイメージの上書きなし -- 拡張機能は公式
postgres:XXイメージのファイルを置き換えてはなりません。 -
共有ライブラリ依存関係 --
lddが結合イメージ内のすべての.soに対して実行され、欠落している推移的依存関係を検出します。 -
CREATE EXTENSION -- 全ての拡張機能が結合イメージで正常にロードされます。
-
機能的スモークテスト -- 各拡張機能は実際のクエリ(ロードだけではない)で実行され、ランタイム動作を確認します。
-
統合テスト -- 各拡張機能の
test.sqlファイルは、PASS/FAILアサーションを含む複数ステップの検証を実行します。
例:出力:
---- Phase 3: Checking for file collisions between extensions...
PASS pgvector <-> postgis: no collisions
...
PASS No file collisions detected between any extension pair
---- Phase 5: Building combined image and checking shared libraries...
PASS All shared library dependencies resolve
---- Phase 6: Functional tests...
PASS CREATE EXTENSION vector
PASS smoke: pgvector similarity
...
---- Phase 7: Integration tests (extensions/*/test.sql)...
PASS integration pgvector (3 checks)
PASS integration postgis (4 checks)
...
========================================
Results: 699 passed, 0 failed, 0 warnings
========================================
コンテナの検証
docker runコマンドを実行した後、コンテナはバックグラウンドで起動します(-dフラグ)。実行中であることを確認するには:
# 実行中のコンテナを一覧表示 -- STATUS "Up" を探します
docker ps
# コンテナログを確認し、「database system is ready to accept connections」を探します
docker logs <container_id>
PostgreSQLに接続して動作を確認するには:
# 実行中のコンテナ内から接続
docker exec -it <container_id> psql -U postgres -c "SELECT version();"
<container_id>をdocker psで表示されたID(またはその最初の数文字)に置き換えてください。
ポートのエクスポートと変更
デフォルトでは、上記の例はホストマシンにポートを公開しません。コンテナ外からPostgreSQLにアクセスするには、-pを追加します:
# pglayers(PostgreSQL)をデフォルトポート(5432)で公開
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-full:17
ポート5432が既に(別のPostgreSQLインスタンスなどで)使用されている場合は、別のホストポートにマッピングします:
# 代わりにホストポート5433を使用します(コンテナは内部で5432でリッスンし続けます)
docker run -d -p 5433:5432 -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-full:17
その後、ポートを指定して接続します:
psql -h localhost -p 5433 -U postgres
フォーマットは-p <host_port>:<container_port>です。ホストポート(左側)のみを変更する必要があります。コンテナは常に5432でリッスンします。
貢献
拡張機能の追加、バグ報告、変更の送信に関する完全なガイドについては、CONTRIBUTING.mdを参照してください。
プロジェクト構造
pglayers/
├── Makefile ビルドインターフェース
├── Dockerfile 統合イメージ(全拡張機能)
├── Dockerfile.apt 全APT拡張機能のための共有ビルド
├── CONTRIBUTING.md 貢献ガイド
├── AGENTS.md エージェント/CI指示
├── scripts/
│ ├── apt-support.sh PGDG利用可能性+バージョンプローブ
│ ├── apt-lock.sh .github/apt-versions.jsonを生成
│ ├── ext-version.sh 拡張機能のビルドバージョンを解決
│ ├── detect-license.sh Debian copyrightからのライセンス検出
│ ├── check-licenses.sh ライセンスポリシーの強制
│ └── licenses.conf 許可/拒否/例外ライセンスリスト
├── .github/
│ ├── base-image-digests.json 追跡対象のベースイメージダイジェスト
│ ├── apt-versions.json 記録されたaptバージョン(PGメジャーごとに)
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml バグレポートフォーム
│ │ ├── new_extension.yml 拡張機能リクエストフォーム
│ │ └── config.yml テンプレート選択設定
│ └── workflows/
│ ├── ci.yml CI:ビルド+テスト+プロファイル構成;マージ時に公開
│ ├── monitor-base-image.yml ベースイメージの更新を検出(6時間ごと)
│ ├── monitor-extensions.yml ソースビルドリリースを検出
│ ├── monitor-apt-versions.yml aptバージョンを追跡(apt-versions.json)
│ └── cache-cleanup.yml GHAキャッシュをクリーンアップ
├── extensions/
│ ├── pgvector/ APT拡張機能:設定+テストのみ
│ │ ├── extension.conf メタデータ(APT_PACKAGE、ライセンスなど)
│ │ └── test.sql 統合テスト(PASS/FAILアサーション)
│ ├── pg_net/ ソースビルド:独自のDockerfileを追加
│ ├── postgis/ カスタムAPT Dockerfile(ライブラリをバンドル)
│ ├── ... (80以上の拡張機能)
│ └── wal2json/
├── profiles/
│ ├── azure.txt Azure PostgreSQL Flexible Server拡張機能
│ └── full.txt 全拡張機能(CI検証済み)
├── tests/
│ ├── test-layers.sh フルテストスイート(衝突+機能)
│ └── test-image.sh 統合イメージに対するクイック統合テスト
└── examples/
└── Dockerfile.example エンドユーザー参照
ライセンスポリシー
このプロジェクトは、寛容なオープンソースライセンス(PostgreSQL, MIT, ISC, Zlib, Apache-2.0, BSDファミリー、および安全な弱/ファイルレベルのコピーレフトMPL-2.0と寛容に分類されるArtistic-2.0)で拡張機能を提供しており、業界慣習が明確にそれを支持する場合には、PostgreSQLの動的拡張メカニズムを介してロードされるGPL-2.0拡張機能も提供します。
このポリシーはscripts/licenses.confにコード化されており、CIでのmake check-licensesによって自動的に強制されます。ソース利用可能ライセンス(BSL/BUSL, SSPL, FSL, Elastic-2.0/ELv2)および感染性コピーレフト(GPL/LGPL/AGPL)は拒否されます。postgisとpgroutingは、文書化された意図的な例外として記録されています。各拡張機能のライセンスは、追加時にDebian copyrightから自動検出されます(コントリビューティングガイド参照)。
GPL-2.0拡張機能(PostGIS, pgRouting)
PostGISとpgRoutingはGPL-2.0ライセンスです。厳密に解釈すると、GPLはGPLコードと「リンク」するあらゆるプログラムに適用される可能性があります。しかし、PostgreSQL拡張機能は、安定した公開API(CREATE EXTENSION)を介してdlopen()で実行時にロードされるため、PostgreSQLコミュニティおよび広範な業界では、結合された作業ではなく「単なる集約」として扱われています:
- 全てのマネージドPostgreSQLサービス(AWS RDS, Azure, Google Cloud SQL, Neon, Supabase)は、PostGISとpgRoutingを同じ方法で配布しています。
- Docker Hubの公式
postgis/postgisDockerイメージは、同一のCOPY --fromパターンを使用しています。 - 動的ロードされたPostgreSQL拡張機能の配布者に対して、GPL違反の訴訟が起こされたことは一度もありません。
- PostgreSQLプロジェクトは、この解釈の下で20年以上運用されています。
これらの拡張機能を含めるのは、実際のリスクがゼロであり、除外するとプロジェクトの有用性が大幅に低下するためです。法務チームがこの解釈に同意しない場合は、DockerfileからPostGISおよびpgRoutingのCOPY --from行を単純に削除してください。
除外する拡張機能
| ライセンス | ポリシー | 例 |
|---|---|---|
| GPL-3.0 | 除外(より強力なコピーレフト、業界コンセンサスが少ない) | login_hook, session_variable |
| AGPL-3.0 | 除外 | topn |
| BSL, SSPL, ELv2, FSL | 除外(オープンソースではない) | -- |
| プロプライエタリ依存関係が必要 | 除外 | oracle_fdw (Oracle Instant Client) |
実質的に意味すること
| ライセンス | 含まれるか? | 例 |
|---|---|---|
| PostgreSQL, MIT, BSD, Apache 2.0, ISC | はい | pgvector, pg_cron, pgaudit, timescaledb |
| MPL-2.0(弱ファイルレベルコピーレフト) | はい | pg_uuidv7 |
| GPL-2.0(動的拡張機能ロード) | はい | PostGIS, pgRouting |
| GPL-3.0 | いいえ | login_hook, session_variable |
| AGPL-3.0 | いいえ | -- |
| BSL, SSPL, ELv2, FSL | いいえ | -- |
FAQ
pglayersはどのように機能しますか?
各拡張機能は、拡張機能のファイル(共有ライブラリ、コントロールファイル、SQLスクリプト)のみを含む最小限のFROM scratch Dockerイメージとしてビルドされます。これらのイメージは実行可能なコンテナではなく、ファイルシステムレイヤーです。
以下のように記述した場合:
COPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /
Dockerは、拡張機能ファイルを公式postgresイメージの正しいパス(/usr/lib/postgresql/17/lib/、/usr/share/postgresql/17/extension/)にコピーします。PostgreSQLはそれらを見つけ、CREATE EXTENSIONを実行できます。コンパイル、パッケージマネージャー、ランタイム依存関係の解決は不要です。公式イメージの上にファイルコピーを積み重ねるだけです。
なぜ拡張機能YのバージョンXが利用できないのですか?
pglayersは意図的なバージョンポリシーに従っています。私たちは、この優先順位で、最新鋭リリースよりも安定性と再現性を重視しています:
-
PGDG APTパッケージ(推奨) -- ほとんどの拡張機能は、公式PostgreSQL APTリポジトリ(
apt.postgresql.org)からインストールされます。取得するバージョンは、PGDGメンテナーがパッケージ化したものです。これは通常最新の安定版リリースですが、アップストリームより数日または数週間遅れる場合があります。 -
ソースビルド(フォールバック) -- PGDGで利用できない拡張機能は、最新の安定版リリースタグのソースからコンパイルされます。
PGDGリポジトリがアップストリームよりも古いバージョンを出荷する場合、私たちはその古いバージョンを出荷します。これは意図的です。PGDGパッケージは対応するPostgreSQLリリースに対してテストされ、同じチャネルを通じてセキュリティパッチを受け取り、ABI互換性が保証されています。PGDGがまだパッケージ化していない新しいリリースに重大なバグ修正またはセキュリティ問題がある場合にのみ、これを上書きします。
なぜ私の拡張機能が含まれていないのですか?
以下のいずれかの可能性があります:
-
ライセンス -- pglayersは、寛容なオープンソースライセンス(PostgreSQL, MIT, BSD, Apache 2.0, ISC)を持つ拡張機能のみを提供します。プロプライエタリ、ソース利用可能(BSL, SSPL, FSL, ELv2)、および強力なコピーレフト(AGPL)ライセンスは除外します。また、プロプライエタリなランタイム依存関係(例:Oracleクライアント)を必要とする拡張機能も除外します。詳細については、ライセンスポリシーセクションを参照してください。
-
まだ貢献されていない -- 貢献を歓迎します!新しい拡張機能を追加するには、コントリビューティングガイドで完全なチェックリスト、Dockerfileパターン、およびテスト要件を確認してください。
なぜ私のPostgreSQLバージョン用のパッケージがないのですか?
PostgreSQLバージョンごとの拡張機能の可用性は、アップストリームのサポートに依存します:
-
APTベースの拡張機能 -- PGDGリポジトリがそのPGバージョン用のパッケージを公開したときに利用可能になります。新しいメジャーPGバージョン(例:ベータ版のPG 19)には、まだ全てのパッケージが利用できない場合があります。
-
ソースビルドの拡張機能 -- 拡張機能がそのPGバージョン用のヘッダーに対してクリーンにコンパイルできる場合に利用可能になります。
必要な拡張機能がまだPGバージョンをサポートしていない場合は、コントリビューティングガイドに従って貢献できます。
謝辞
このプロジェクトは、PostgreSQLコミュニティの肩の上に成り立っています:
- PostgreSQL Global Development Group:最高のオープンソースデータベースを構築してくれたこと
- PGDG APT Repositoryメンテナー:DebianおよびUbuntu向けの拡張機能をパッケージ化・配布してくれたこと
- 公式PostgreSQL Docker imageメンテナー:信頼性が高く、適切に設定されたベースイメージを提供してくれたこと
- Debian PostgreSQL team:これら全てを可能にするパッケージング作業をしてくれたこと
- 寛容なオープンソースライセンスの下で作品をリリースした全ての拡張機能の作者
pglayersは、彼らの作業の上に構築された薄い自動化レイヤーです。アップストリームエコシステムの品質と一貫性がなければ、このプロジェクトは存在しなかったでしょう。