PostgreSQL Database management ============================== .. raw:: html CloudNativePGは、デフォルトで\ ``app`` という名前のアプリケーションデータベースを自動的に作成することにより、PostgreSQLデータベースのプロビジョニングを簡素化します。このデフォルトの動作については、 :ref:`空のクラスターをブートストラップする `initdb` <空のクラスターをブートストラップする `initdb`>` で説明しています セクション。 より高度なユースケースのために、CloudNativePGは **宣言的データベース管理** を導入します。これにより、ユーザーは\ ``Database`` カスタムリソース定義CRDを使用してPostgreSQLデータベースのライフサイクルを定義および制御できます。この方法はKubernetesとシームレスに統合し、PostgreSQLデータベースを管理するためのスケーラブルで自動化された一貫したアプローチを提供します。 -------------- 主要なコンセプト ---------------- 管理範囲 ^^^^^^^^ .. Note:: CloudNativePGは、データベース、ロール、テーブルスペースを含むPostgreSQLクラスターの**グローバルオブジェクト**を管理します。ただし、拡張機能とスキーマテーブルなどを超えてデータベースコンテンツは管理しません**。データベースのコンテンツを管理するには、専用のツールを使用するか、アプリケーション自分自身に依存します。 　 宣言的な\ ``Database`` マニフェスト ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 次の例は、 ``Database`` リソースが\ ``Cluster`` とどのように相互作用するかを示しています。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: name: cluster-example-one spec: name: one owner: app cluster: name: cluster-example extensions: - name: bloom ensure: present 適用されると、このマニフェストは、 ``cluster-example`` PostgreSQLクラスター内の\ ``app`` ロールが所有する\ ``one`` という名前のデータベースを要求する\ ``cluster-example-one`` と呼ばれる\ ``Database`` オブジェクトを作成します。 .. Note:: :ref:`API Reference ` を参照してください。 各\ ``Database`` オブジェクトに定義できる属性の完全なリスト。 　 ``Database`` マニフェストの必須フィールド ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``metadata.name`` 名前空間内のKubernetesオブジェクトの一意の名前。 - ``spec.name`` PostgreSQLに表示されるデータベースの名前。 - ``spec.owner`` データベースを所有するPostgreSQLロール。 - ``spec.cluster.name`` ターゲットPostgreSQLクラスターの名前。 ``Database`` オブジェクトは特定の\ ``Cluster`` を参照し、データベースを作成する場所を決定する必要があります。クラスターのプライマリインスタンスによって管理され、データベースが必要に応じて作成または更新されます。 .. Note:: `metadata.name` と`spec.name` の違いにより、複数の`Database` リソースは、同じKubernetes名前空間内の異なるCloudNativePGクラスターにわたって同じ名前のデータベースを参照できます。 　 予約されたデータベース名 ------------------------ PostgreSQLは、 ``postgres`` 、\ ``template0`` 、\ ``template1`` などのデータベースを自動的に作成します。これらの名前は予約されており、CloudNativePGの新しい\ ``Database`` オブジェクトに使用できません。 .. Note:: `spec.name` を`postgres` 、`template0` 、または`template1` に設定して`Database` を作成することはできません。 　 調整とステータス ---------------- ``Database`` オブジェクトが正常にリコンサイルされると、 - ``status.applied`` は\ ``true`` に設定されます。 - ``status.observedGeneration`` は、最後に適用された構成の\ ``metadata.generation`` と一致します。 リコンサイルされた\ ``Database`` オブジェクトの例 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: generation: 1 name: cluster-example-one spec: cluster: name: cluster-example name: one owner: app status: observedGeneration: 1 applied: true リコンシリエーション中にエラーが発生した場合、\ ``status.applied`` は\ ``false`` になり、エラーメッセージは\ ``status.message`` フィールドに含まれます。 データベースの削除 ------------------ CloudNativePGは、データベース削除の2つの方法をサポートしています。 1. ``delete`` 再利用ポリシーの使用 2. データベースの\ ``ensure`` フィールドを\ ``absent`` に宣言的に設定する ``delete`` 再利用ポリシーを介した削除 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``databaseReclaimPolicy`` フィールドは、\ ``Database`` オブジェクトが削除されたときの動作を決定します。 - ``retain`` デフォルト データベースは、手動管理のためにPostgreSQLに残ります。 - ``delete`` データベースはPostgreSQLから自動的に削除されます。 例 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: name: cluster-example-two spec: databaseReclaimPolicy: delete name: two owner: app cluster: name: cluster-example この\ ``Database`` オブジェクトを削除すると、\ ``cluster-example`` クラスターから\ ``two`` データベースが自動的に削除されます。 ``ensure: absent`` の宣言的設定 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ データベースを削除するには、次の例のように\ ``ensure`` フィールドを\ ``absent`` に設定します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: name: cluster-example-database-to-drop spec: cluster: name: cluster-example name: database-to-drop owner: app ensure: absent このマニフェストは、 ``database-to-drop`` データベースが\ ``cluster-example`` クラスターから削除されることを保証します。 データベース内の拡張機能の管理 ------------------------------ .. Note:: 拡張機能はグローバルオブジェクトではなくデータベーススコープですが、CloudNativePGはそれらを管理するための宣言型インターフェイスを提供します。特定の拡張機能のインストールにはスーパーユーザー権限が必要になる場合があるため、このアプローチが必要です。CloudNativePGは、デフォルトで無効にすることをお勧めします。このAPIを活用することにより、ユーザーは昇格した特権を必要とせずに、スケーラブルで制御された方法で拡張機能を効率的に管理できます。 　 CloudNativePGは、ターゲットデータベース内のPostgreSQL拡張機能の管理を簡素化および自動化します。 この機能を有効にするには、次の例に示すように、拡張仕様のリストを使用して\ ``spec.extensions`` フィールドを定義します。 .. code:: yaml ## ... spec: extensions: - name: bloom ensure: present ## ... 各拡張エントリは、次のプロパティをサポートしています。 - ``name`` *必須* 拡張機能の名前。 - ``ensure`` 拡張機能がデータベースに存在するかどうかを指定します。 - ``present`` 拡張機能がインストールされていることを確認しますデフォルト - ``absent`` 拡張機能が削除されたことを確認します。 - ``version`` インストールまたはアップグレードする拡張機能の特定のバージョン。 - ``schema`` 拡張機能をインストールするスキーマ。 .. Note:: CloudNativePGは、次のPostgreSQLのSQLコマンドを使用して拡張機能を管理します。 `CREATE EXTENSION `_ 、 `DROP EXTENSION `_ 、 `ALTER EXTENSION `_ ``UPDATE TO`` および\ ``SET SCHEMA`` に限定します。 　 オペレーターは、\ ``spec.extensions`` に明示的にリストされている拡張子のみをリコンサイルします。このリストで指定されていない既存の拡張子は変更されないままです。 .. Warning:: 宣言的拡張機能管理を導入する前、CloudNativePGは、構成から拡張機能を作成する簡単な方法を提供していません。これに対処するために、 :ref:`マネージド拡張機能 <マネージド拡張機能>` 機能が導入され、\ ``pg_stat_statements`` のような主要な拡張機能の自動かつ透過的な管理が可能になります。現在、\ ``Database`` CRDの拡張機能サポートと管理対象拡張機能の間で競合がないことを確認するのはあなたの責任です。 　 データベースでのスキーマの管理 ------------------------------ .. Note:: PostgreSQLのスキーマ管理は、グローバルオブジェクトの管理に対するCloudNativePGの主な焦点の例外です。スキーマはデータベース内に存在するため、通常はアプリケーション開発プロセスの一部として管理されます。ただし、CloudNativePGは、主にスキーマ内での拡張機能の展開のサポートを完了するために、スキーマ管理の宣言的インターフェイスを提供します。 　 CloudNativePGは、ターゲットデータベース内のPostgreSQLスキーマの管理を簡素化および自動化します。 この機能を有効にするには、次の例に示すように、スキーマ仕様のリストを使用して\ ``spec.schemas`` フィールドを定義します。 .. code:: yaml ## ... spec: schemas: - name: app owner: app ## ... 各スキーマエントリは、次のプロパティをサポートしています。 - ``name`` *(必須)* スキーマの名前。 - ``owner`` スキーマの所有者。 - ``ensure`` データベースにスキーマが存在するかどうかを指定します。 - ``present`` スキーマがインストールされていることを確認しますデフォルト。 - ``absent`` スキーマが削除されたことを確認します。 .. Note:: CloudNativePGは、 PostgreSQLのSQLコマンド `CREATE SCHEMA `_ 、 `DROP SCHEMA `_ 、 `ALTER SCHEMA `_ を使用してスキーマを管理します。 データベースでの外部データラッパーFDWの管理 ------------------------------------------- .. Note:: 外部データラッパーFDWは、データベーススコープのオブジェクトであり、通常、作成または変更するにはスーパーユーザー権限が必要です。 CloudNativePGは、FDWを管理するための宣言型APIを提供し、ユーザーがSQLコマンドを直接実行したり、特権をエスカレートしたりせずに、制御されたKubernetesネイティブの方法でFDWを定義および保守できます。 CloudNativePGは、宣言的構成を使用して、ターゲットデータベース内のPostgreSQL外部データラッパーのシームレスで自動管理を可能にします。 この機能を有効にするには、次の例に示すように、FDW仕様のリストを使用して\ ``spec.fdws`` フィールドを定義します。 .. code:: yaml ## ... spec: fdws: - name: postgres_fdw usage: - name: app type: grant ## ... 各FDWエントリは、次のプロパティをサポートしています。 - ``name`` 外部データラッパーの名前 **必須)** 。 - ``ensure`` データベースでFDWが\ ``present`` または\ ``absent`` であるかどうかを示しますデフォルトは\ ``present`` です。 - ``handler`` FDWが使用するハンドラーファンクションの名前。指定しない場合、FDW拡張機能がある場合に定義されたデフォルトハンドラーが使用されます。 - ``validator`` FDWが使用するバリデーターファンクションの名前。指定しない場合、FDW拡張機能がある場合に定義されたデフォルトのバリデーターが使用されます。 - ``owner`` FDWの所有者 **スーパーユーザーである必要があります** 。 - ``usage`` 次のフィールドを含むFDWの\ ``USAGE`` 権限のリスト。 - ``name`` 使用権限を付与するまたは取り消すロールの名前 **(必須)** . - ``type`` : 使用許可の種類。 ``grant`` および\ ``revoke`` をサポートします。 - ``options`` 管理するFDW固有のオプションのマップ。各キーはオプションの名前です。各オプションは次のフィールドをサポートします。 - ``value`` オプションの文字列値。 - ``ensure`` オプションが\ ``present`` または\ ``absent`` であるかどうかを示します。 .. Note:: `handler` と`validator` は両方ともオプショナルであり、指定しない場合、FDW拡張機能存在する場合に定義されたデフォルトのハンドラーとバリデーターが使用されます。 `handler` または`validator` を`"-"` に設定すると、それぞれFDWからハンドラーまたはバリデータが削除されます。これはPostgreSQLの規則に従います。ここで、「-」はハンドラーまたはバリデーターが存在しないことを示します。 　 .. Warning:: PostgreSQLは、外部データラッパーの所有権を**スーパーユーザー権限のみを持つロール**に制限しています。 PostgreSQLは外部データラッパーの非スーパーユーザーの所有権を許可していないため、所有権を非スーパーユーザーアプリロールなどに割り当てようとすると無視されるか、拒否されます。デフォルトでは、これらは`postgres` ユーザーが所有しています。 　 オペレーターは、\ ``spec.fdws`` に明示的にリストされたFDWのみをリコンサイルします。このリストで宣言されていない既存のFDWはそのまま残されます。 .. Note:: CloudNativePGは、 PostgreSQLのネイティブSQLコマンド `CREATE FOREIGN DATA WRAPPER `_ 、 `ALTER FOREIGN DATA WRAPPER `_ 、および `DROP FOREIGN DATA WRAPPER `_ を使用してFDWを管理します。 `ALTER` コマンドは、オプションの更新をサポートしています。 データベース内の外部サーバーの管理 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CloudNativePGは、宣言的構成を使用して、ターゲットデータベース内のPostgreSQL外部サーバーのシームレスな自動管理を提供します。 **外部サーバー** は、外部データラッパーFDWが外部データソースにアクセスするために使用する接続の詳細をカプセル化します。ユーザー固有の接続の詳細については、 `user mappings `_ を定義できます。 .. Note:: CloudNativePGは現在、ユーザーマッピングの宣言的構成をサポートしていません。ただし、FDWとその外部サーバーが定義されると、標準のデータベースロールに使用特権を付与できます。これにより、スーパーユーザー権限を必要とせずに、 SQLスキーマの一部としてユーザーマッピングを管理できます。 この機能を有効にするには、外部サーバー仕様のリストを使用して\ ``Database`` リソースの\ ``spec.servers`` フィールドを宣言します。例 .. code:: yaml ## ... spec: servers: - name: angus fdw: postgres_fdw ensure: present usage: - name: app type: grant options: - name: host value: angus-rw - name: dbname value: app ## ... 各外部サーバーエントリは、次のプロパティをサポートしています。 - ``name`` 外部サーバーの名前 **必須)** 。 - ``fdw`` サーバーが属する外部データラッパーの名前 **必須** 。 - ``ensure`` 外部サーバーをデータベース内の\ ``present`` または\ ``absent`` にするかどうかデフォルト\ ``present`` 。 - ``usage`` 次のフィールドを含む外部サーバーの\ ``USAGE`` 権限のリスト。 - ``name`` 使用権限を付与するまたは取り消すロールの名前 **(必須)** . - ``type`` 使用権限の種類。 ``grant`` および\ ``revoke`` をサポートします。 - ``options`` FDW固有のオプション仕様のリスト。リスト内の各エントリは、次のキーをサポートします。 - ``name`` オプションの名前 **必須** . - ``value`` オプションの文字列値。 - ``ensure`` オプションが\ ``present`` または\ ``absent`` かどうかを示します。 .. Note:: 　 ``fdw`` フィールドは、データベースで既に定義された既存の外部データラッパーを参照する必要があります。指定されたFDWが存在しない場合、外部サーバーは作成されません。 .. Note:: 　 CloudNativePGは、 PostgreSQLのネイティブSQLコマンド `CREATE SERVER `_ 、 `ALTER SERVER `_ 、および `DROP SERVER `_ を使用して外部サーバーを管理します。 ``ALTER SERVER`` コマンドは、サーバーオプションを更新するために使用されます。 オペレーターは、\ ``spec.servers`` に明示的にリストされている外部サーバーのみをリコンサイルします。このリストに含まれない既存のサーバーは変更されないままです。 制限と注意事項 -------------- データベースの名前の変更 ^^^^^^^^^^^^^^^^^^^^^^^^ CloudNativePGはPostgreSQLの `CREATE DATABASE `_ および `ALTER DATABASE `_ に準拠していますが コマンド、 **データベースの名前の変更はサポートされていません** 。既存の\ ``Database`` オブジェクトの\ ``spec.name`` を変更しようとすると、Kubernetesによって拒否されます。 データベースの作成と変更 ^^^^^^^^^^^^^^^^^^^^^^^^ - 新しいデータベースの場合、CloudNativePGは\ ``CREATE DATABASE`` ステートメントを使用します。 - 既存のデータベースの場合、\ ``ALTER DATABASE`` を使用して変更を適用します。 これら2つのPostgresコマンドにはいくつかの違いがあることに注意することが重要です。特に、\ ``ALTER`` によって受け入れられるオプションは、\ ``CREATE`` によって受け入れられるオプションのサブセットです。 .. Warning:: エンコードや照合設定などの一部のフィールドは、PostgreSQLで不変です。既存のデータベースのこれらのフィールドを変更しようとすると、無視されます。 　 レプリカクラスター ^^^^^^^^^^^^^^^^^^ レプリカには書き込み特権がないため、レプリカクラスターで宣言されたデータベースオブジェクトは適用できません。これらのオブジェクトは、レプリカが昇格するまで保留状態のままです。 競合の解決 ^^^^^^^^^^ 同じ名前空間内の2つの\ ``Database`` オブジェクトが同じPostgreSQLデータベースつまり同一の\ ``spec.name`` および\ ``spec.cluster.name`` を管理している場合、2番目のオブジェクトは拒否されます。 ステータスメッセージの例 .. code:: yaml status: applied: false message: reconciliation error: database "one" is already managed by Database object "cluster-example-one" Postgresバージョンの違い ^^^^^^^^^^^^^^^^^^^^^^^^ CloudNativePGは、PostgreSQLの機能を遵守しています。たとえば、PostgreSQL 16で導入された\ ``ICU_RULES`` のような機能は、以前のバージョンでは使用できません。 PostgreSQLからのエラーは、\ ``Database`` オブジェクトの\ ``status`` に反映されます。 手動変更 ^^^^^^^^ CloudNativePGは、データベースへの手動変更を上書きしません。リコンサイルが完了すると、 ``Database`` オブジェクトは、 ``metadata.generation`` が変更しない限り再適用されないため、 PostgreSQLを直接変更するための柔軟性が得られます。