PostgreSQL Database management

CloudNativePGは、デフォルトでapp という名前のアプリケーションデータベースを自動的に作成することにより、PostgreSQLデータベースのプロビジョニングを簡素化します。このデフォルトの動作については、 空のクラスターをブートストラップする `initdb <空のクラスターをブートストラップする initdb>` で説明しています

セクション。

より高度なユースケースのために、CloudNativePGは 宣言的データベース管理 を導入します。これにより、ユーザーはDatabase カスタムリソース定義CRDを使用してPostgreSQLデータベースのライフサイクルを定義および制御できます。この方法はKubernetesとシームレスに統合し、PostgreSQLデータベースを管理するためのスケーラブルで自動化された一貫したアプローチを提供します。

主要なコンセプト

管理範囲

注釈

CloudNativePGは、データベース、ロール、テーブルスペースを含むPostgreSQLクラスターの**グローバルオブジェクト**を管理します。ただし、拡張機能とスキーマテーブルなどを超えてデータベースコンテンツは管理しません**。データベースのコンテンツを管理するには、専用のツールを使用するか、アプリケーション自分自身に依存します。

宣言的なDatabase マニフェスト

次の例は、 Database リソースがCluster とどのように相互作用するかを示しています。

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 オブジェクトを作成します。

注釈

API Reference を参照してください。

各Database オブジェクトに定義できる属性の完全なリスト。

Database マニフェストの必須フィールド

  • metadata.name 名前空間内のKubernetesオブジェクトの一意の名前。

  • spec.name PostgreSQLに表示されるデータベースの名前。

  • spec.owner データベースを所有するPostgreSQLロール。

  • spec.cluster.name ターゲットPostgreSQLクラスターの名前。

Database オブジェクトは特定のCluster を参照し、データベースを作成する場所を決定する必要があります。クラスターのプライマリインスタンスによって管理され、データベースが必要に応じて作成または更新されます。

注釈

metadata.name と`spec.name` の違いにより、複数の`Database` リソースは、同じKubernetes名前空間内の異なるCloudNativePGクラスターにわたって同じ名前のデータベースを参照できます。

予約されたデータベース名

PostgreSQLは、 postgres 、template0 、template1 などのデータベースを自動的に作成します。これらの名前は予約されており、CloudNativePGの新しいDatabase オブジェクトに使用できません。

注釈

spec.name を`postgres` 、template0 、または`template1` に設定して`Database` を作成することはできません。

調整とステータス

Database オブジェクトが正常にリコンサイルされると、

  • status.applied はtrue に設定されます。

  • status.observedGeneration は、最後に適用された構成のmetadata.generation と一致します。

リコンサイルされたDatabase オブジェクトの例

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から自動的に削除されます。

例

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 に設定します。

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 クラスターから削除されることを保証します。

データベース内の拡張機能の管理

注釈

拡張機能はグローバルオブジェクトではなくデータベーススコープですが、CloudNativePGはそれらを管理するための宣言型インターフェイスを提供します。特定の拡張機能のインストールにはスーパーユーザー権限が必要になる場合があるため、このアプローチが必要です。CloudNativePGは、デフォルトで無効にすることをお勧めします。このAPIを活用することにより、ユーザーは昇格した特権を必要とせずに、スケーラブルで制御された方法で拡張機能を効率的に管理できます。

CloudNativePGは、ターゲットデータベース内のPostgreSQL拡張機能の管理を簡素化および自動化します。

この機能を有効にするには、次の例に示すように、拡張仕様のリストを使用してspec.extensions フィールドを定義します。

##  ...

spec:
  extensions:
    - name: bloom
      ensure: present

##  ...

各拡張エントリは、次のプロパティをサポートしています。

  • name 必須 拡張機能の名前。

  • ensure 拡張機能がデータベースに存在するかどうかを指定します。

    • present 拡張機能がインストールされていることを確認しますデフォルト

    • absent 拡張機能が削除されたことを確認します。

  • version インストールまたはアップグレードする拡張機能の特定のバージョン。

  • schema 拡張機能をインストールするスキーマ。

注釈

CloudNativePGは、次のPostgreSQLのSQLコマンドを使用して拡張機能を管理します。 CREATE EXTENSION 、 DROP EXTENSION 、 ALTER EXTENSION

UPDATE TO およびSET SCHEMA に限定します。

オペレーターは、spec.extensions に明示的にリストされている拡張子のみをリコンサイルします。このリストで指定されていない既存の拡張子は変更されないままです。

警告

宣言的拡張機能管理を導入する前、CloudNativePGは、構成から拡張機能を作成する簡単な方法を提供していません。これに対処するために、 マネージド拡張機能

機能が導入され、pg_stat_statements のような主要な拡張機能の自動かつ透過的な管理が可能になります。現在、Database CRDの拡張機能サポートと管理対象拡張機能の間で競合がないことを確認するのはあなたの責任です。

データベースでのスキーマの管理

注釈

PostgreSQLのスキーマ管理は、グローバルオブジェクトの管理に対するCloudNativePGの主な焦点の例外です。スキーマはデータベース内に存在するため、通常はアプリケーション開発プロセスの一部として管理されます。ただし、CloudNativePGは、主にスキーマ内での拡張機能の展開のサポートを完了するために、スキーマ管理の宣言的インターフェイスを提供します。

CloudNativePGは、ターゲットデータベース内のPostgreSQLスキーマの管理を簡素化および自動化します。

この機能を有効にするには、次の例に示すように、スキーマ仕様のリストを使用してspec.schemas フィールドを定義します。

##  ...

spec:
  schemas:
    - name: app
      owner: app

##  ...

各スキーマエントリは、次のプロパティをサポートしています。

  • name (必須) スキーマの名前。

  • owner スキーマの所有者。

  • ensure データベースにスキーマが存在するかどうかを指定します。

    • present スキーマがインストールされていることを確認しますデフォルト。

    • absent スキーマが削除されたことを確認します。

注釈

CloudNativePGは、 PostgreSQLのSQLコマンド CREATE SCHEMA 、 DROP SCHEMA 、 ALTER SCHEMA を使用してスキーマを管理します。

データベースでの外部データラッパーFDWの管理

注釈

外部データラッパーFDWは、データベーススコープのオブジェクトであり、通常、作成または変更するにはスーパーユーザー権限が必要です。 CloudNativePGは、FDWを管理するための宣言型APIを提供し、ユーザーがSQLコマンドを直接実行したり、特権をエスカレートしたりせずに、制御されたKubernetesネイティブの方法でFDWを定義および保守できます。

CloudNativePGは、宣言的構成を使用して、ターゲットデータベース内のPostgreSQL外部データラッパーのシームレスで自動管理を可能にします。

この機能を有効にするには、次の例に示すように、FDW仕様のリストを使用してspec.fdws フィールドを定義します。

##  ...

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 であるかどうかを示します。

注釈

handler と`validator` は両方ともオプショナルであり、指定しない場合、FDW拡張機能存在する場合に定義されたデフォルトのハンドラーとバリデーターが使用されます。 handler または`validator` を`"-"` に設定すると、それぞれFDWからハンドラーまたはバリデータが削除されます。これはPostgreSQLの規則に従います。ここで、「-」はハンドラーまたはバリデーターが存在しないことを示します。

警告

PostgreSQLは、外部データラッパーの所有権を**スーパーユーザー権限のみを持つロール**に制限しています。 PostgreSQLは外部データラッパーの非スーパーユーザーの所有権を許可していないため、所有権を非スーパーユーザーアプリロールなどに割り当てようとすると無視されるか、拒否されます。デフォルトでは、これらは`postgres` ユーザーが所有しています。

オペレーターは、spec.fdws に明示的にリストされたFDWのみをリコンサイルします。このリストで宣言されていない既存のFDWはそのまま残されます。

注釈

CloudNativePGは、 PostgreSQLのネイティブSQLコマンド CREATE FOREIGN DATA WRAPPER 、 ALTER FOREIGN DATA WRAPPER 、および DROP FOREIGN DATA WRAPPER を使用してFDWを管理します。 ALTER コマンドは、オプションの更新をサポートしています。

データベース内の外部サーバーの管理

CloudNativePGは、宣言的構成を使用して、ターゲットデータベース内のPostgreSQL外部サーバーのシームレスな自動管理を提供します。

外部サーバー は、外部データラッパーFDWが外部データソースにアクセスするために使用する接続の詳細をカプセル化します。ユーザー固有の接続の詳細については、 user mappings を定義できます。

注釈

CloudNativePGは現在、ユーザーマッピングの宣言的構成をサポートしていません。ただし、FDWとその外部サーバーが定義されると、標準のデータベースロールに使用特権を付与できます。これにより、スーパーユーザー権限を必要とせずに、 SQLスキーマの一部としてユーザーマッピングを管理できます。

この機能を有効にするには、外部サーバー仕様のリストを使用してDatabase リソースのspec.servers フィールドを宣言します。例

##  ...

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 かどうかを示します。

fdw フィールドは、データベースで既に定義された既存の外部データラッパーを参照する必要があります。指定されたFDWが存在しない場合、外部サーバーは作成されません。

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 によって受け入れられるオプションのサブセットです。

警告

エンコードや照合設定などの一部のフィールドは、PostgreSQLで不変です。既存のデータベースのこれらのフィールドを変更しようとすると、無視されます。

レプリカクラスター

レプリカには書き込み特権がないため、レプリカクラスターで宣言されたデータベースオブジェクトは適用できません。これらのオブジェクトは、レプリカが昇格するまで保留状態のままです。

競合の解決

同じ名前空間内の2つのDatabase オブジェクトが同じPostgreSQLデータベースつまり同一のspec.name およびspec.cluster.name を管理している場合、2番目のオブジェクトは拒否されます。

ステータスメッセージの例

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を直接変更するための柔軟性が得られます。