diff --git a/docs/enterprise/debian/components/ace.md b/docs/enterprise/debian/components/ace.md new file mode 100644 index 0000000..f768112 --- /dev/null +++ b/docs/enterprise/debian/components/ace.md @@ -0,0 +1,200 @@ +# Installing and Configuring ACE + +ACE (Active Consistency Engine) is designed to ensure and maintain data +consistency across nodes in a distributed pgEdge Distributed Postgres +cluster. ACE identifies and resolves data inconsistencies, schema +differences, and replication configuration mismatches across cluster +nodes. + +## Installing ACE + +ACE supports Debian 11 (Bullseye), Debian 12 (Bookworm), Debian 13 +(Trixie), Ubuntu 22.04 (Jammy), and Ubuntu 24.04 (Noble). Use the +following command to install ACE: + +```bash +sudo apt-get install pgedge-ace +``` + +The following table describes the files and directories the package +creates: + +| Path | Description | +|------|-------------| +| `/usr/bin/ace` | ACE binary | +| `/etc/systemd/system/pgedge-ace.service` | systemd service file | +| `/var/log/pgedge/ace` | ACE log directory | +| `/var/lib/pgedge/ace` | ACE configuration directory | + +## Initializing ACE + +Before starting the ACE service, initialize the configuration files. +Run the following commands to generate the default configuration +templates: + +```bash +ace cluster init --path /var/lib/pgedge/ace/pg_service.conf +ace config init --path /var/lib/pgedge/ace/ace.yaml +``` + +The following table describes the two files the commands create: + +| File | Purpose | +|------|---------| +| `pg_service.conf` | Cluster and node connection definitions | +| `ace.yaml` | ACE runtime configuration | + +!!! note + ACE looks for `ace.yaml` in the working directory by default. Since + the service runs from `/var/lib/pgedge/ace/`, always initialize + configuration files in that directory. + +## Configuring ACE + +This section describes the two configuration files that control ACE +behavior. + +### pg_service.conf + +The `pg_service.conf` file defines your cluster and nodes. The file +follows PostgreSQL service file format. Each cluster has a base section +and one section per node named `.`. In the following +example, the configuration defines a two-node cluster named `prod`: + +```ini +[prod] +dbname=mydb +user=aceuser +password=yourpassword + +[prod.n1] +host=10.0.0.1 +port=5432 + +[prod.n2] +host=10.0.0.2 +port=5432 +``` + +### ace.yaml + +The `ace.yaml` file controls ACE runtime behavior. In the following +example, the configuration shows the key settings to review after +initialization: + +```yaml +pg_service_file: /var/lib/pgedge/ace/pg_service.conf +default_cluster: demo +max_cpu_ratio: 0.6 +block_rows: 10000 +``` + +For automated scheduled jobs, add `schedule_jobs` and `schedule_config` +sections to `ace.yaml`. See the +[ACE documentation](https://docs.pgedge.com/ace/) for details about +scheduling options. + +## Starting the ACE Service + +Once the configuration files are in place, use the following steps to +enable and start the ACE service. + +1. Enable the ACE service to start on boot: + + ```bash + sudo systemctl enable pgedge-ace + ``` + +2. Start the ACE service: + + ```bash + sudo systemctl start pgedge-ace + ``` + +3. Check the service status: + + ```bash + sudo systemctl status pgedge-ace + ``` + +All ACE service logs are written to `/var/log/pgedge/ace/ace.log`. Use +the following command to follow the logs in real time: + +```bash +tail -f /var/log/pgedge/ace/ace.log +``` + +## Verifying the Installation + +Run a table diff against your cluster to confirm ACE can connect to all +nodes: + +```bash +cd /var/lib/pgedge/ace +ace table-diff demo public.your_table +``` + +## Troubleshooting + +This section describes common errors and their resolutions. + +### The 'ace.yaml' configuration file is not found + +ACE looks for `ace.yaml` in the current working directory. Run ACE from +`/var/lib/pgedge/ace/` or specify the path explicitly using the +`--config` flag. + +### The pgcrypto extension is not available + +Install the PostgreSQL contrib package with the following command: + +```bash +sudo apt-get install postgresql-contrib +``` + +After installing the contrib package, re-run the command with +`--ensure-pgcrypto`. + +### Can not retrieve commit timestamp data + +Enable commit timestamp tracking and restart PostgreSQL on all nodes: + +```bash +sudo -u postgres psql -c "ALTER SYSTEM SET track_commit_timestamp = on;" +sudo systemctl restart postgresql +``` + +### Subscription worker not streaming (pid is NULL) + +This error usually indicates a replication conflict. Check the +PostgreSQL logs with the following command: + +```bash +sudo tail -50 /var/log/postgresql/$(ls -t /var/log/postgresql/ | head -1) +``` + +Recreate the subscription with `origin = none` to prevent replication +loops: + +```sql +ALTER SUBSCRIPTION sub_from_node2 DISABLE; +ALTER SUBSCRIPTION sub_from_node2 SET (slot_name = NONE); +DROP SUBSCRIPTION sub_from_node2; + +CREATE SUBSCRIPTION sub_from_node2 + CONNECTION 'host=127.0.0.1 port=5433 dbname=postgres user=postgres' + PUBLICATION pub_node2 + WITH (copy_data = false, connect = true, origin = none); +``` + +## Resources + +The following resources provide additional information about installing +and using ACE: + +- The [ACE GitHub repository](https://github.com/pgEdge/ace) contains + the source code and issue tracker. +- The [ACE documentation](https://docs.pgedge.com/ace/) describes all + commands and configuration options. +- The [ACE release notes](https://docs.pgedge.com/ace/CHANGELOG/) + describe changes by version. diff --git a/docs/enterprise/debian/components/components.md b/docs/enterprise/debian/components/components.md index eb365cb..7f221ad 100644 --- a/docs/enterprise/debian/components/components.md +++ b/docs/enterprise/debian/components/components.md @@ -29,6 +29,7 @@ matches your copy of Postgres. | [pgEdge DocLoader](https://docs.pgedge.com/pgedge-docloader/) | pgedge-docloader | Document loading utility | | [pgEdge RAG Server](https://docs.pgedge.com/pgedge-rag-server/) | pgedge-rag-server | Retrieval-Augmented Generation server | | [pgEdge Vectorizer](https://docs.pgedge.com/pgedge-vectorizer/) | pgedge-vectorizer_XX | Vector embedding generation | +| [ACE](ace.md) | pgedge-ace | Active Consistency Engine for cluster data validation | | [Lolor](https://docs.pgedge.com/lolor/blob/main/README.md) | pgedge-lolor_XX | Logical-logical replication | | [pgAdmin](https://www.pgadmin.org/docs/) | pgedge-pgadmin4; pgedge-pgadmin4-desktop; pgedge-pgadmin4-server; pgedge-pgadmin4-web | Web-based database management tool | | [pgaudit](https://github.com/pgaudit/pgaudit/blob/main/README.md) | pgedge-pgaudit_XX | Session and object audit logging | diff --git a/docs/enterprise/el/components/ace.md b/docs/enterprise/el/components/ace.md new file mode 100644 index 0000000..164500d --- /dev/null +++ b/docs/enterprise/el/components/ace.md @@ -0,0 +1,197 @@ +# Installing and Configuring ACE + +ACE (Active Consistency Engine) is designed to ensure and maintain data +consistency across nodes in a distributed pgEdge Distributed Postgres +cluster. ACE identifies and resolves data inconsistencies, schema +differences, and replication configuration mismatches across cluster +nodes. + +## Installing ACE + +ACE supports RHEL, CentOS, and Rocky Linux versions 9 and 10. Use the +following command to install ACE: + +```bash +sudo dnf install pgedge-ace +``` + +The following table describes the files and directories the package creates: + +| Path | Description | +|------|-------------| +| `/usr/bin/ace` | ACE binary | +| `/etc/systemd/system/pgedge-ace.service` | systemd service file | +| `/var/log/pgedge/ace` | ACE log directory | +| `/var/lib/pgedge/ace` | ACE configuration directory | + + +## Initializing ACE + +Before starting the ACE service, initialize the configuration files. +Run the following commands to generate the default configuration templates: + +```bash +ace cluster init --path /var/lib/pgedge/ace/pg_service.conf +ace config init --path /var/lib/pgedge/ace/ace.yaml +``` + +The following table describes the two files the commands create: + +| File | Purpose | +|------|---------| +| `pg_service.conf` | Cluster and node connection definitions | +| `ace.yaml` | ACE runtime configuration | + +!!! note + ACE looks for `ace.yaml` in the working directory by default. Since + the service runs from `/var/lib/pgedge/ace/`, always initialize + configuration files in that directory. + +## Configuring ACE + +This section describes the two configuration files that control ACE +behavior. + +### pg_service.conf + +The `pg_service.conf` file defines your cluster and nodes. The file +follows PostgreSQL service file format. Each cluster has a base section +and one section per node named `.`. In the following +example, the configuration defines a two-node cluster named `prod`: + +```ini +[prod] +dbname=mydb +user=aceuser +password=yourpassword + +[prod.n1] +host=10.0.0.1 +port=5432 + +[prod.n2] +host=10.0.0.2 +port=5432 +``` + +### ace.yaml + +The `ace.yaml` file controls ACE runtime behavior. In the following +example, the configuration shows the key settings to review after +initialization: + +```yaml +pg_service_file: /var/lib/pgedge/ace/pg_service.conf +default_cluster: demo +max_cpu_ratio: 0.6 +block_rows: 10000 +``` + +For automated scheduled jobs, add `schedule_jobs` and `schedule_config` +sections to `ace.yaml`. See the +[ACE documentation](https://docs.pgedge.com/ace/) for details about +scheduling options. + +## Starting the ACE Service + +Once the configuration files are in place, use the following steps to enable +and start the ACE service. + +1. Enable the ACE service to start on boot: + + ```bash + sudo systemctl enable pgedge-ace + ``` + +2. Start the ACE service: + + ```bash + sudo systemctl start pgedge-ace + ``` + +3. Check the service status: + + ```bash + sudo systemctl status pgedge-ace + ``` + +All ACE service logs are written to `/var/log/pgedge/ace/ace.log`. Use the +following command to follow the logs in real time: + +```bash +tail -f /var/log/pgedge/ace/ace.log +``` + +## Verifying the Installation + +Run a table diff against your cluster to confirm ACE can connect to all nodes: + +```bash +cd /var/lib/pgedge/ace +ace table-diff demo public.your_table +``` + +## Troubleshooting + +This section describes common errors and their resolutions. + +### The 'ace.yaml' configuration file is not found + +ACE looks for `ace.yaml` in the current working directory. Run ACE from +`/var/lib/pgedge/ace/` or specify the path explicitly using the +`--config` flag. + +### The pgcrypto extension is not available + +Install the PostgreSQL contrib package with the following command: + +```bash +sudo dnf install postgresql17-contrib +``` + +After installing the contrib package, re-run the command with +`--ensure-pgcrypto`. + +### Can not retrieve commit timestamp data + +Enable commit timestamp tracking and restart PostgreSQL on all nodes: + +```bash +sudo -u postgres psql -c "ALTER SYSTEM SET track_commit_timestamp = on;" +sudo systemctl restart postgresql-17 +``` + +### Subscription worker not streaming (pid is NULL) + +This error usually indicates a replication conflict. Check the +PostgreSQL logs with the following command: + +```bash +sudo tail -50 /var/lib/pgsql/17/data/log/$(ls -t /var/lib/pgsql/17/data/log/ | head -1) +``` + +Recreate the subscription with `origin = none` to prevent replication +loops: + +```sql +ALTER SUBSCRIPTION sub_from_node2 DISABLE; +ALTER SUBSCRIPTION sub_from_node2 SET (slot_name = NONE); +DROP SUBSCRIPTION sub_from_node2; + +CREATE SUBSCRIPTION sub_from_node2 + CONNECTION 'host=127.0.0.1 port=5433 dbname=postgres user=postgres' + PUBLICATION pub_node2 + WITH (copy_data = false, connect = true, origin = none); +``` + +## Resources + +The following resources provide additional information about installing and +using ACE: + +- The [ACE GitHub repository](https://github.com/pgEdge/ace) contains + the source code and issue tracker. +- The [ACE documentation](https://docs.pgedge.com/ace/) describes all + commands and configuration options. +- The [ACE release notes](https://docs.pgedge.com/ace/CHANGELOG/) + describe changes by version. diff --git a/docs/enterprise/el/components/components.md b/docs/enterprise/el/components/components.md index aa1b02d..a6369a0 100644 --- a/docs/enterprise/el/components/components.md +++ b/docs/enterprise/el/components/components.md @@ -29,6 +29,7 @@ ensure you've installed the version that matches your copy of Postgres. | [pgEdge DocLoader](https://docs.pgedge.com/pgedge-docloader/) | pgedge-docloader | Document loading utility | | [pgEdge RAG Server](https://docs.pgedge.com/pgedge-rag-server/) | pgedge-rag-server | Retrieval-Augmented Generation server | | [pgEdge Vectorizer](https://docs.pgedge.com/pgedge-vectorizer/) | pgedge-vectorizer_XX | Vector embedding generation | +| [ACE](ace.md) | pgedge-ace | Active Consistency Engine for cluster data validation | | [Lolor](https://docs.pgedge.com/lolor/blob/main/README.md) | pgedge-lolor_XX | Logical-logical replication | | [pgAdmin](https://www.pgadmin.org/docs/) | pgedge-pgadmin4; pgedge-pgadmin4-desktop; pgedge-pgadmin4-server; pgedge-pgadmin4-web | Web-based database management tool | | [pgaudit](https://github.com/pgaudit/pgaudit/blob/main/README.md) | pgedge-pgaudit_XX | Session and object audit logging | diff --git a/mkdocs.yml b/mkdocs.yml index 7a5bdc4..a947e25 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -346,6 +346,7 @@ nav: - Installing Postgres: enterprise/el/installing.md - Supporting Components: - Installing Supporting Components: enterprise/el/components/components.md + - Configuring ACE: enterprise/el/components/ace.md - Configuring Patroni: enterprise/el/components/patroni.md - Configuring PgBouncer: enterprise/el/components/pgbouncer.md - Migrating to pgEdge Enterprise Postgres: enterprise/el/migrating.md @@ -357,6 +358,7 @@ nav: - Installing Postgres: enterprise/debian/installing.md - Supporting Components: - Installing Supporting Components: enterprise/debian/components/components.md + - Configuring ACE: enterprise/debian/components/ace.md - Configuring Patroni: enterprise/debian/components/patroni.md - Configuring PgBouncer: enterprise/debian/components/pgbouncer.md - Migrating to pgEdge Enterprise Postgres: enterprise/debian/migrating.md