Using PGD CLI ============= PGD CLIは、EDB Postgres分散PGDクラスターを管理およびモニタリングするためのコマンドラインインターフェイスです。ノードの作成、ノードの参加、レプリケーションの管理など、クラスターでさまざまな操作を実行するためのコマンドセットを提供します。 :ref:`Creating your first cluster ` を使用している場合、それは既にインストールと構成されています。 PGDクラスターの最初のホストにログインします。 .. code:: shell docker compose exec host-1 bash そして、 PGD CLIのバージョンを確認します。 .. code:: sql pgd --version __OUTPUT__ pgd-cli version Version 6.4.0 .. Note:: `docker compose exec` コマンドを使用して、PGDクラスターの最初のホストのコンテキストで実行することにより、コンテナの外部から次のコマンドを実行することもできます。 .. code:: shell docker compose exec host-1 pgd また、それらはすべてPGD CLIがインストールおよび構成されているため、クラスター内の任意のホストから\ ``pgd`` コマンドを実行できます。 .. :: ## PGD CLIの入門 ``pgd cluster show`` コマンドを使用して、クラスターの全体的なステータスを表示することから始めます。 .. code:: shell pgd cluster show __OUTPUT__ # Summary Group Name | Parent Group | Group Type | Node Name | Node Kind - -----------+--------------+------------+-----------+----------- group-1 | pgd | data | node-1 | data group-1 | pgd | data | node-2 | data group-1 | pgd | data | node-3 | data pgd | | global | | # Health Check | Status | Details - ------------------+--------+------------------------------------------------- Connections | Ok | All BDR nodes are accessible Raft | Ok | Raft Consensus is working correctly Replication Slots | Ok | All PGD replication slots are working correctly Clock Skew | Ok | Clock drift is within permissible limit Versions | Ok | All nodes are running the same PGD version # Clock Drift Reference Node | Node Name | Clock Drift - ---------------+-----------+------------- node-3 | node-2 | * node-3 | node-1 | * このコマンドは、クラスター、そのノード、およびそれらの正常性ステータスの概要を提供します。また、ノード間のクロックドリフトも示します。これは、レプリケーションの一貫性にとって重要です。 ``pgd node show`` コマンドを使用して、個々のノードのステータスを表示することもできます。 .. code:: shell pgd node node-1 show __OUTPUT__ # Summary Node Property | Value - ----------------+------------ Node Name | node-1 Group Name | group-1 Node Kind | data Join State | ACTIVE Node Status | Up Node ID | 4153941939 Snowflake SeqID | 1 Database | pgddb # Options Option Name | Option Value - ---------------+-------------------------------------------------- route_dsn | port=5432 dbname=pgddb host=host-1 user=postgres route_fence | false route_priority | -1 route_reads | true route_writes | true pgd CLIコマンドの構造は階層的で、コマンドは機能ごとにグループ化されています。次を実行して、使用可能なコマンドとその説明を表示できます。 .. code:: shell pgd --help __OUTPUT__ Manages PGD clusters Usage: pgd [OPTIONS] Commands: cluster Cluster-level commands group Group related commands groups Groups listing commands node Node related commands nodes Nodes listing commands events Event log commands replication Replication related commands raft Raft related commands commit-scope Commit scope management commands assess PGD compatibility assessment of Postgres server completion Generate the autocompletion script for pgd for the specified shell Options: -V, --version Print version Global Options: -f, --config-file Sets the configuration file path --dsn Sets the PostgreSQL connection string e.g. "host=localhost port=6000 user=postgres dbname=postgres" [env: PGD_CLI_DSN=] -o, --output Sets the output format for tables [env: PGD_CLI_OUTPUT=] [default: psql] [possible values: json, psql, modern, markdown, simple] --debug Print debug messages, useful while troubleshooting [env: PGD_CLI_DEBUG=] -h, --help Print help ``group`` 、\ ``node`` などのコマンドは、次の引数としてグループまたはノード名を取り、特定のコマンドが続きます。 ``cluster`` 、\ ``groups`` 、\ ``nodes`` などのコマンドは、クラスターレベルで動作するか、すべてのグループまたはノードをリストするため、グループ名またはノード名を必要としません。 次のコマンドを実行して、特定のコマンドのヘルプを取得することもできます。 .. code:: shell pgd --help クラスターステータスの表示 -------------------------- PGDクラスターの全体的なステータスを表示するために、既に ``pgd cluster show`` コマンドを使用しています。これは、すべてのクラスター情報を表示します。クラスターの正常性ステータスのみを表示するには、 ``--health`` オプションを使用できます。 .. code:: shell pgd cluster show --health __OUTPUT__ Check | Status | Details - ------------------+--------+------------------------------------------------- Connections | Ok | All BDR nodes are accessible Raft | Ok | Raft Consensus is working correctly Replication Slots | Ok | All PGD replication slots are working correctly Clock Skew | Ok | Clock drift is within permissible limit Versions | Ok | All nodes are running the same PGD version または、概要ステータスのみを表示する場合は、 ``--summary`` オプションを使用できます。 .. code:: shell pgd cluster show --summary __OUTPUT__ Group Name | Parent Group | Group Type | Node Name | Node Kind - -----------+--------------+------------+-----------+----------- group-1 | pgd | data | node-1 | data group-1 | pgd | data | node-2 | data group-1 | pgd | data | node-3 | data pgd | | global | | グループとグループステータスの表示 ---------------------------------- クラスター内のすべてのグループのステータスを表示するには、 ``pgd groups list`` コマンドを使用できます。 .. code:: shell pgd groups list __OUTPUT__ Group Name | Parent Group Name | Group Type | Nodes - -----------+-------------------+------------+------- group-1 | pgd | data | 3 pgd | | global | 0 これで、トップレベルグループ\ ``pgd`` と、3つのノードを含むデータグループ\ ``group-1`` が表示されます。すべてのノードは、クラスター全体のすべてのアクティビティを調整するトップレベルグループのメンバーです。データグループ\ ``group-1`` は、自分自身間でデータを複製し、グループ内の着信クエリーをグループ内の書き込みリーダーノードにルーティングする3つのデータノードのグループです。 ``pgd group show`` コマンドを使用して、グループの詳細を深く掘り下げることができます。 .. code:: shell pgd group group-1 show __OUTPUT__ # Summary Group Property | Value - ------------------+--------- Group Name | group-1 Parent Group Name | pgd Group Type | data Write Leader | node-1 Commit Scope | # Nodes Node Name | Node Kind | Join State | Node Status - ----------+-----------+------------+------------- node-1 | data | ACTIVE | Up node-2 | data | ACTIVE | Up node-3 | data | ACTIVE | Up # Options Option Name | Option Value - ----------------------------------+---------------------- analytics_storage_location | (inherited) apply_delay | 00:00:00 (inherited) check_constraints | true (inherited) default_commit_scope | (inherited) enable_raft | true enable_routing | true enable_wal_decoder | false (inherited) http_port | (inherited) location | num_writers | -1 (inherited) read_only_consensus_timeout | (inherited) read_only_max_client_connections | (inherited) read_only_max_server_connections | (inherited) read_only_port | (inherited) read_write_consensus_timeout | (inherited) read_write_max_client_connections | (inherited) read_write_max_server_connections | (inherited) read_write_port | (inherited) route_reader_max_lag | -1 route_writer_max_lag | -1 route_writer_wait_flush | false streaming_mode | default (inherited) use_https | true このコマンドは、グループ、そのノード、およびそれらのステータスの概要を提供します。また、ルーティングが有効になっているかどうか、監視用のHTTPポート、その他の構成設定などのグループオプションも表示します。 clusterコマンドと同様に、 ``--summary`` オプションを使用して、グループの概要のみを表示することもできます。 .. code:: shell pgd group group-1 show --summary __OUTPUT__ Group Property | Value - ------------------+--------- Group Name | group-1 Parent Group Name | pgd Group Type | data Write Leader | node-1 Commit Scope | これで、グループがトップレベルグループ\ ``pgd`` の子であり、データグループであり、グループの書き込みリーダーノードが\ ``node-1`` であることがわかります。このグループにはコミットスコープが設定されていません。これは、デフォルトのコミットスコープを使用していることを意味します。 ``--nodes`` オプションは、グループ内のノードを表示するために使用できます。 .. code:: shell pgd group group-1 show --nodes __OUTPUT__ Node Name | Node Kind | Join State | Node Status - ----------+-----------+------------+------------- node-1 | data | ACTIVE | Up node-2 | data | ACTIVE | Up node-3 | data | ACTIVE | Up また、同様に、 ``--options`` オプションを使用してグループオプションを表示できます。 .. code:: shell pgd group group-1 show --options __OUTPUT__ Option Name | Option Value - ----------------------------------+---------------------- analytics_storage_location | (inherited) apply_delay | 00:00:00 (inherited) check_constraints | true (inherited) default_commit_scope | (inherited) enable_raft | true enable_routing | true enable_wal_decoder | false (inherited) http_port | (inherited) location | num_writers | -1 (inherited) read_only_consensus_timeout | (inherited) read_only_max_client_connections | (inherited) read_only_max_server_connections | (inherited) read_only_port | (inherited) read_write_consensus_timeout | (inherited) read_write_max_client_connections | (inherited) read_write_max_server_connections | (inherited) read_write_port | (inherited) route_reader_max_lag | -1 route_writer_max_lag | -1 route_writer_wait_flush | false streaming_mode | default (inherited) use_https | true ご覧のとおり、オプションの多くは親グループであるトップレベルグループ\ ``pgd`` から継承されます。 ``enable_raft`` および\ ``enable_routing`` オプションは\ ``true`` に設定されています。これは、グループがレプリケーションと書き込みリーダーノードへのルーティングクエリにRaftコンセンサスを使用していることを意味します。接続マネージャーポートを介して作成されます。 ``pgd group pgd show`` コマンドを使用して、親グループ ``pgd`` を見てみましょう。 .. code:: shell pgd group pgd show __OUTPUT__ # Summary Group Property | Value - ------------------+-------- Group Name | pgd Parent Group Name | Group Type | global Write Leader | Commit Scope | これは、トップレベルグループ ``pgd`` がグローバルグループであることを示しています。これは、データグループではなく、独自のデータノードを持たないことを意味します。この場合、クラスター内のデータグループのアクティビティを調整するためにのみ使用されます。データノードがないため、書き込みリーダーはありません。 出力の次の部分には、グループ内のノードが表示されますが、空です。 .. code:: console # Nodes Node Name | Node Kind | Join State | Node Status - ----------+-----------+------------+------------- ``pgd`` グループのオプションを次に示します。 .. code:: console # Options Option Name | Option Value - ----------------------------------+-------------- analytics_storage_location | apply_delay | 00:00:00 check_constraints | true default_commit_scope | enable_raft | true enable_routing | false enable_wal_decoder | false http_port | location | num_writers | -1 read_only_consensus_timeout | read_only_max_client_connections | read_only_max_server_connections | read_only_port | read_write_consensus_timeout | read_write_max_client_connections | read_write_max_server_connections | read_write_port | route_reader_max_lag | -1 route_writer_max_lag | -1 route_writer_wait_flush | false streaming_mode | default use_https | true これらは、トップレベルグループ\ ``pgd`` のオプションです。これは、\ ``group-1`` がオプションを継承する場所です。ただし、ここでは ``enable_routing`` オプションは\ ``false`` に設定されています。これは、トップレベルグループが独自のデータノードを持たないため、クエリーをデータノードにルーティングしないことを意味します。 ``enable_raft`` オプションは\ ``true`` に設定されています。これは、トップレベルグループがRaftコンセンサスを使用してクラスターの管理を調整することを意味します。 オプションが設定されていない場合、デフォルト値が使用されます。たとえば、 ``00:00:00`` に設定される\ ``apply_delay`` オプション、つまりクラスターへの変更の適用に遅延がないことを意味します。 ノードとノードのステータスの表示 -------------------------------- クラスター内のすべてのノードのステータスを表示するには、 ``pgd nodes list`` コマンドを使用できます。 .. code:: shell pgd nodes list __OUTPUT__ Node Name | Group Name | Node Kind | Join State | Node Status - -----------+------------+-----------+------------+------------- node-1 | group-1 | data | ACTIVE | Up node-2 | group-1 | data | ACTIVE | Up node-3 | group-1 | data | ACTIVE | Up ``pgd node show`` コマンドを使用して、特定のノードのステータスを表示することもできます。 .. code:: shell pgd node node-1 show __OUTPUT__ # Summary Node Property | Value - ----------------+------------ Node Name | node-1 Group Name | group-1 Node Kind | data Join State | ACTIVE Node Status | Up Node ID | 4153941939 Snowflake SeqID | 1 Database | pgddb # Options Option Name | Option Value - ---------------+-------------------------------------------------- route_dsn | port=5432 dbname=pgddb host=host-1 user=postgres route_fence | false route_priority | -1 route_reads | true route_writes | true ここで、ノード自分自身についての詳細を確認できます。ノードの名前とそれが属しているグループ、それがデータノードであること、グループにアクティブに参加していること、および実行中であることがわかります。ノードIDはノードの一意の識別子であり、Snowflake SeqIDは、クラスター内のイベントを順序付けするために使用されます。最後に、そのデータベースが\ ``pgddb`` 、Quickstart Docker Composeキットで作成されたデフォルトデータベースであることがわかります。 ノードのオプションを次に示します。これらはこの特定のノードに固有です。 - ``route_dsn`` は、ノードの接続文字列であり、接続マネージャーがクエリーをこのノードにルーティングするために使用されます。 - ``route_fence`` は\ ``false`` に設定されています。これは、ノードにクエリのルーティングを防止するフェンス設定がないことを意味します。 - ``route_priority`` は\ ``-1`` に設定されています。これは、ノードがルーティングクエリーに特定の優先度を持たないことを意味します。 - ``route_reads`` および\ ``route_writes`` は両方とも\ ``true`` に設定されています。これは、ノードが読み取りクエリと書き込みクエリの両方を処理できることを意味します。 これらは、接続マネージャーがクエリーをノードにルーティングするときに使用します。これらは、ダウンせずにアクティブなノードを制御する方法でもあります。 ``route_fence`` を\ ``true`` に設定すると、接続マネージャーがクエリをこのノードにルーティングできなくなりますが、クラスターの一部でデータをレプリケートすることはできます。 ノードオプションの設定 ---------------------- ``pgd node set`` コマンドを使用してノードのオプションを設定できます。たとえば、 ``node-1`` の\ ``route_fence`` オプションを\ ``true`` に設定するには、次のコマンドを実行できます。 .. code:: shell pgd node node-1 set-option route_fence true ``node-1`` の接続マネージャーに接続してみると .. code:: shell psql -h host-1 -p 6432 接続が得られます。ただし、ルーティングクエリーからフェンスされているため、\ ``node-1`` ノードにルーティングされません。代わりに、グループ内の現在の書き込みリーダー\ ``node-2`` にルーティングされます。 .. code:: sql select node_name from bdr.local_node_summary; node_name ----------- node-2 (1 row) 次を実行してフェンシングを終了して元に戻すと .. code:: shell pgd node node-1 set-option route_fence false ``node-1`` ノードの接続マネージャーに再度接続できるようになりました。 .. code:: shell psql -h host-1 -p 6432 そして、\ ``node-1`` ノードに接続されたことがわかります。 .. code:: sql select node_name from bdr.local_node_summary; node_name ----------- node-1 (1 row)