Importing Postgres databases ============================ .. raw:: html このセクションでは、新しいCloudNativePGクラスター内に1つ以上の既存のPostgreSQLデータベースをインポートする方法について説明します。 インポート操作は、PostgreSQLのオンライン論理バックアップの概念に基づいており、オリジンホストへのネットワーク接続を介して\ ``pg_dump`` 、および\ ``pg_restore`` に依存します。ネイティブのマルチバージョン同時実行制御MVCCとスナップショットのおかげで、PostgreSQLでは、書き込みアクティビティを停止せずに、ネットワークを介して同時実行の方法で、一貫したバックアップを取得できます。 論理バックアップは、PostgreSQLバージョンのメジャーアップグレードを実行するための最も一般的な柔軟で信頼性の高い技術でもあります。 その結果、このセクションの手順は両方の場合に適しています。 - Kubernetesの外部でも、既存のPostgreSQLインスタンスから1つ以上のデータベースをインポート - PostgreSQLバージョンから同じまたは新しいバージョンにデータベースをインポートし、PostgreSQLの *メジャーアップグレード* を有効にしますバージョン13.xからバージョン17.xなど .. Warning:: PostgreSQLのメジャーアップグレードを実行するときは、アプリケーションが新しいバージョンと互換性があり、データベース拡張機能を含むオブジェクトのアップグレードパスが実行可能であることを確認する責任があります。 　 どちらの場合も、操作は元のデータベースの一貫した **スナップショット** で実行されます。 .. Note:: このため、バックアップの開始後にソースデータベースに行われた変更は宛先クラスタにないため、 `Cluster` リソースの最終インポートの前にソースの書き込み操作を停止することをお勧めします。したがって、この機能が参照される理由「オフラインインポート」または「オフラインメジャーアップグレード」として。 　 その仕組み ---------- 概念的には、インポートには、 :ref:`空のクラスターをブートストラップする `initdb` <空のクラスターをブートストラップする `initdb`>` を使用して新しいクラスター *宛先クラスター* を作成し、 ``initdb.import`` サブセクションを完了して、既存のPostgresクラスター *ソースクラスター* からオブジェクトをインポートする必要があります。 PostgreSQLの推奨事項に従って、 *宛先クラスター* のPostgreSQLメジャーバージョンが *ソースクラスター* のバージョン以上であることをお勧めします。 CloudNativePGは、ソースクラスターから宛先クラスターにオブジェクトをインポートする2つの主な方法を提供します。 - **マイクロサービスアプローチ** 宛先クラスターは、CloudNativePGプロジェクトで推奨されているように、指定されたアプリケーションユーザーが所有する単一のアプリケーションデータベースをホストするように設計されています - **モノリスアプローチ** 宛先クラスターは、ソースクラスターからインポートされた複数のデータベースとさまざまなユーザーをホストするように設計されています。 最初のインポート方法は\ ``microservice`` タイプを介して使用でき、2番目は\ ``monolith`` タイプを介して使用できます。 .. Warning:: 宛先クラスターが、スーパーユーザーまたは`pg_dump` で論理バックアップを取るための十分な特権を持つユーザーでソースクラスターにアクセスできることを確認するのはあなたの責任です。 `PostgreSQL documentation on `pg_dump` `_ を参照してください。 詳細については、 　 ``microservice`` タイプ ----------------------- マイクロサービスアプローチでは、ソースクラスターから宛先クラスターにインポートする単一のデータベースを指定できます。操作は4つのステップで実行されます。 - 新しいクラスターの\ ``initdb`` ブートストラップ - ``pg_dump -Fd`` を使用した選択したデータベース\ ``initdb.import.databases`` 内のエクスポート - ``initdb.owner`` ユーザーが所有する\ ``initdb.database`` アプリケーションデータベースへの\ ``pg_restore --no-acl --no-owner`` を使用したデータベースのインポート - データベースダンプファイルのクリーンアップ - ``postImportApplicationSQL`` パラメーターを介してアプリケーションデータベースでのユーザー定義のSQLクエリーのオプションの実行 - インポートされたデータベースでの\ ``ANALYZE VERBOSE`` の実行 次の図では、 *N* データベースを含む単一のPostgreSQLクラスターが別のCloudNativePGクラスターにインポートされ、各クラスターが *N* ソースデータベースのいずれかに対するマイクロサービスインポートを使用します。 .. figure:: /images/microservice-import.png :width: 70% :alt: Example of microservice import type Example of microservice import type たとえば、以下のYAMLは、 ``postgres`` に接続することにより、\ ``cluster-pg96`` クラスターサポートされていないPostgreSQL 9.6から\ ``angus`` データベースをインポートする\ ``cluster-microservice`` と呼ばれる新しい3インスタンスのPostgreSQLクラスターオペレーターがリリースされた時点での利用可能な最新のメジャーバージョンを作成します\ ``cluster-pg96-superuser`` シークレットに保存されたパスワードを介して、 ``postgres`` ユーザーを使用してデータベースにアクセスします。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-microservice spec: instances: 3 bootstrap: initdb: import: type: microservice databases: - angus source: externalCluster: cluster-pg96 #postImportApplicationSQL: #- | # INSERT YOUR SQL QUERIES HERE storage: size: 1Gi externalClusters: - name: cluster-pg96 connectionParameters: # Use the correct IP or host name for the source database host: pg96.local user: postgres dbname: postgres password: name: cluster-pg96-superuser key: password .. Warning:: 上記の例では、コミュニティ、したがってCloudNativePGでサポートされていないバージョンのPostgreSQLを実行しているソースデータベースを意図的に使用しています。ソースインスタンスからのデータのエクスポートは、宛先クラスターの`pg_dump` のバージョンを使用して実行されます。これは、サポートされているものであり、ソースのものと同等以上である必要があります。私たちの経験に基づいて、データをエクスポートするこの方法はPostgresの古いバージョンのサポートされていないバージョンでも動作するため、古いデータをKubernetes内のより良いシステムに移動する機会が得られます。これが、このセクションの例で9.6を使用した主な理由です。この領域で問題が発生した場合は、ご連絡をお待ちしております。 　 ``microservice`` タイプを使用するときは、いくつか注意する必要があります。 - インポートするデータを含む既存のPostgreSQLインスタンスをポイントする\ ``externalCluster`` が必要です。詳細については、 :ref:``externalClusters` セクション <`externalClusters` セクション>` を参照してください。 - オペレーション中にKubernetesクラスターと\ ``externalCluster`` の間でトラフィックを許可する必要がある - ソースデータベースへの接続は、\ ``pg_dump`` を実行し、ロール情報を読み取る必要がある指定されたユーザーで付与される必要があります *スーパーユーザー* はOKです - 現在、\ ``pg_dump -Fd`` 結果は\ ``PGDATA`` ボリュームの\ ``dumps`` フォルダー内に一時的に保存されます。そのため、割り当てられたノードにダンプ結果、復元されたデータとインデックスを一時的に含むための十分な利用可能な領域が必要です。インポート操作が完了すると、このフォルダーはオペレーターによって自動的に削除されます。 - ``initdb.import.databases`` 配列内で指定できるデータベースは1つだけです - ロールはインポートされません - そのため、\ ``initdb.import.roles`` 内で指定できません .. tip:: マイクロサービスアプローチは、宛先クラスターのCloudNativePG規約とデフォルトに従います。宛先クラスターに`initdb.database` または`initdb.owner` を設定しない場合、両方のパラメーターはデフォルトの`app` になります。 　 ``monolith`` タイプ ------------------- モノリスアプローチでは、ソースクラスターから宛先クラスターにインポートするロールとデータベースのセットを指定できます。操作は次の手順で実行されます。 - 新しいクラスターの\ ``initdb`` ブートストラップ - 選択したロールのエクスポートとインポート - ``pg_dump -Fd`` を使用して、選択したデータベース\ ``initdb.import.databases`` 内を一度に1つずつエクスポート - 選択した各データベースを作成し、 ``pg_restore`` を使用してデータをインポートします - インポートされた各データベースで\ ``ANALYZE`` を実行します - データベースダンプファイルのクリーンアップ .. figure:: /images/monolith-import.png :width: 70% :alt: Example of monolith import type Example of monolith import type たとえば、以下のYAMLは、 ``cluster-monolith`` と呼ばれる新しい3インスタンスのPostgreSQLクラスターオペレーターがリリースされた時点での利用可能な最新のメジャーバージョンを作成します。 ``postgres`` ユーザーを使用して\ ``postgres`` データベースに接続し、\ ``cluster-pg96-superuser`` シークレットに保存されているパスワードを介して\ ``postgres`` データベースに接続します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-monolith spec: instances: 3 bootstrap: initdb: import: type: monolith databases: - accounting - banking - resort roles: - accountant - bank_user source: externalCluster: cluster-pg96 storage: size: 1Gi externalClusters: - name: cluster-pg96 connectionParameters: # Use the correct IP or host name for the source database host: pg96.local user: postgres dbname: postgres sslmode: require password: name: cluster-pg96-superuser key: password ``monolith`` タイプを使用するときは、いくつか注意する必要があります。 - インポートするデータを含む既存のPostgreSQLインスタンスをポイントする\ ``externalCluster`` が必要です。詳細については、 :ref:``externalClusters` セクション <`externalClusters` セクション>` を参照してください。 - オペレーション中にKubernetesクラスターと\ ``externalCluster`` の間でトラフィックを許可する必要がある - ソースデータベースへの接続は、\ ``pg_dump`` を実行し、ロール情報を取得する必要がある指定されたユーザーで付与される必要があります *スーパーユーザー* はOKです - 現在、\ ``pg_dump -Fd`` 結果は、宛先クラスターのインスタンスの\ ``PGDATA`` ボリュームの\ ``dumps`` フォルダー内に一時的に保存されます。そのため、割り当てられたノードにダンプ結果、復元されたデータとインデックスを一時的に含むための十分な利用可能な領域が必要です。インポート操作が完了すると、このフォルダーはオペレーターによって自動的に削除されます。 - ``initdb.import.databases`` 配列で指定される少なくとも1つのデータベース - インポートされたデータベースに必要なロールは、 ``initdb.import.roles`` 内で指定する必要があります。以下の制限があります。 - 次のロールが存在する場合、インポートされません。\ ``postgres`` 、\ ``streaming_replica`` 、\ ``cnpg_pooler_pgbouncer`` - ``SUPERUSER`` オプションは、インポートされたロールから削除されます - ワイルドカード\ ``"*"`` は、\ ``databases`` および/または\ ``roles`` 配列の唯一の要素として使用して、その種類のすべてのオブジェクトをインポートできます。データベースを照合する場合、ワイルドカードは\ ``postgres`` データベース、テンプレートデータベース、および接続を許可しないデータベースを無視します - クローンプロシージャが完了した後、すべてのデータベースに対して\ ``ANALYZE VERBOSE`` が実行されます。 - ``postImportApplicationSQL`` フィールドはサポートされていません .. tip:: データベースとその所有者は、ソースクラスターに存在するものとまったく同じように保持されます。インポート中に`app` データベースもユーザーも作成されません。 `bootstrap.initdb` スタンザが、インポートされるデータベースまたはユーザーと一致しないカスタム`database` および`owner` 値を指定している場合、インスタンスマネージャーは、インポートされたデータベースと所有者を変更しないまま、これらの指定された名前で新しい空のアプリケーションデータベースと所有者ロールを作成します。 　 実際の例 -------- ``monolith`` アプローチを使用して単一のデータベースをインポートすることを妨げるものはありません。そうした場合の結果が\ ``microservice`` アプローチを使用した場合とどのように異なるかを見るのは興味深いです。 ロール\ ``me`` が所有する\ ``mydb`` という名前のデータベースを使用するソースクラスター、たとえば、 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example spec: instances: 1 postgresql: pg_hba: - host all all all trust storage: size: 1Gi bootstrap: initdb: database: mydb owner: me ``microservice`` を介してインポートできます。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example-microservice spec: instances: 1 storage: size: 1Gi bootstrap: initdb: import: type: microservice databases: - mydb source: externalCluster: cluster-example externalClusters: - name: cluster-example connectionParameters: host: cluster-example-rw dbname: postgres モノリス経由と同様に .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example-monolith spec: instances: 1 storage: size: 1Gi bootstrap: initdb: import: type: monolith databases: - mydb roles: - me source: externalCluster: cluster-example externalClusters: - name: cluster-example connectionParameters: host: cluster-example-rw dbname: postgres どちらの場合も、データベースの内容はインポートされますが、 - マイクロサービスの場合、インポートされたデータベースの名前と所有者は両方とも\ ``app`` 、またはフィールドの構成のいずれかになります ``database`` および\ ``owner`` が\ ``bootstrap.initdb`` スタンザで設定されています。 - モノリスの場合、データベースと所有者はソースクラスター、つまりそれぞれ\ ``mydb`` および\ ``me`` とまったく同じように保持されます。 ``app`` データベースもユーザーも作成されません。インポートするソースデータベース/所有者と一致しない\ ``bootstrap.initdb`` スタンザの\ ``database`` および\ ``owner`` のカスタム設定がある場合、インスタンスマネージャーは新しい空のアプリケーションデータベースと所有者ロールを作成しますが、インポートされたデータベース/所有者はそのまま残します。 インポートの最適化 ------------------ データベースの論理インポート中に、CloudNativePGは、以下を強制することにより、速度とデータの耐久性を優先するためにPostgreSQLの構成を最適化します。 - ``archive_mode`` 〜\ ``off`` - ``fsync`` 〜\ ``off`` - ``full_page_writes`` 〜\ ``off`` - ``max_wal_senders`` 〜\ ``0`` - ``wal_level`` 〜\ ``minimal`` インポートジョブを完了する前に、CloudNativePGは予想される構成を復元し、\ ``initdb --sync-only`` を実行してデータがディスクに永続的に書き込まれるようにします。 .. Note:: WALアーカイブ要求された場合、およびデータベースのインポート処理が完了した後にWALレベルが受け入れられます。同様に、レプリカはブートストラップフェーズの後に、実際のクラスターリソースが開始されるときにクローン作成されます。 　 インポートフェーズ中に実行できる最適化は他にもあります。このトピックはCloudNativePGの範囲を超えていますが、 ``Cluster`` 構成で\ ``shared_buffers`` 、\ ``max_wal_size`` 、\ ``checkpoint_timeout`` などのPostgres GUCを直接調整することにより、チェックポイント領域への不要な書き込みを削減することをお勧めします。 ``pg_dump`` および\ ``pg_restore`` 動作のカスタマイズ ----------------------------------------------------- ``pgDumpExtraOptions`` および\ ``pgRestoreExtraOptions`` パラメーターを使用して追加オプションを指定することにより、\ ``pg_dump`` および\ ``pg_restore`` の動作をカスタマイズできます。これは、パフォーマンスの向上またはインポート/エクスポートの複雑さの管理に特に役立ちます。 たとえば、並列ジョブを有効にすると、データ転送が大幅に高速化されます。 .. code:: yaml bootstrap: initdb: import: type: microservice databases: - app source: externalCluster: cluster-example pgDumpExtraOptions: - --jobs=2 pgRestoreExtraOptions: - --jobs=2 ステージ固有の\ ``pg_restore`` オプション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ インポートプロセスをより詳細に制御するために、CloudNativePGは次のフェーズでステージ固有の\ ``pg_restore`` オプションをサポートしています。 - ``pre-data`` – 例、スキーマ定義 - ``data`` – 例、テーブルの内容 - ``post-data`` – 例、インデックス、コンストレイン、トリガー フェーズごとにオプションを指定することにより、並列処理を最適化し、復元するオブジェクトの性質に合わせて調整したフラグを適用できます。 .. code:: yaml bootstrap: initdb: import: type: microservice schemaOnly: false databases: - mynewdb source: externalCluster: sourcedb-external pgRestorePredataOptions: - --jobs=1 pgRestoreDataOptions: - --jobs=4 pgRestorePostdataOptions: - --jobs=2 上記の例では - ``--jobs=1`` は\ ``pre-data`` ステージに適用されて、スキーマ作成の順序を保持します。 - ``--jobs=4`` は、 ``data`` ステージでの並列処理を増加させ、大規模なデータのインポートを高速化します。 - ``--jobs=2`` は、 ``post-data`` ステージでのパフォーマンスと依存関係の処理のバランスをとります。 これらのステージ固有の設定は、同時実行の調整によってパフォーマンスが大幅に向上する可能性がある大規模なデータベースまたはリソース依存度の環境で特に役立ちます。 .. Note:: 提供される場合、ステージ固有のオプションは一般的な`pgRestoreExtraOptions` より優先されます。 　 .. Warning:: `pgDumpExtraOptions` 、`pgRestoreExtraOptions` 、およびすべてのステージ固有のリストアオプション`pgRestorePredataOptions` 、`pgRestoreDataOptions` 、`pgRestorePostdataOptions` は、オペレーターによる検証なしで基になるPostgreSQLツールに直接渡されます。特定のフラグは、オペレーターの意図した機能またはデザインと競合する場合があります。これらのオプションは注意して使用し、運用に適用する前に、安全で制御された環境で常に徹底的にテストします。 　 オンラインインポートとアップグレード ------------------------------------ 論理レプリケーションは、次のアプローチを使用して、ネットワーク経由でアクセス可能なPostgreSQLデータベースをインポートする強力な方法を提供します。 - **スキーマのみのオプションを使用したブートストラップのインポート** レプリケーションを開始する前に、ターゲットデータベースのスキーマを初期化します。 - **``Subscription`` リソース** 連続レプリケーションを設定してデータ変更を同期します。 この手法は、最小限のダウンタイムでメジャーPostgreSQLのアップグレードを実行するために活用できるため、シームレスな移行とシステムのアップグレードに最適です。 制限やベストプラクティスを含む詳細については、ドキュメントの :ref:`ロジカルレプリケーションのパブリケーション <ロジカルレプリケーションのパブリケーション>` セクションを参照してください。