ACE Command Reference

ACE API commands are available in two flavors:

• ACE commands for those users who are not using Merkle trees.
• ACE mtree commands for those users who use Merkle trees.

Commands

The commands in the first section of this page are designed for use without Merkle trees.

table-diff

Compares a table between nodes and generates a diff report.

Usage:

./ace table-diff [flags] [cluster] <schema.table>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.
• <schema.table>: The fully qualified name of the table to compare.

Flags:

Example:

./ace table-diff --nodes="n1,n2" --dbname=mydatabase my-cluster public.my_table 

Add --schedule --every=<duration> to keep the comparison running until you cancel the command.

Diff files follow the pattern <schema>_<table>_diffs-<timestamp>.json. When --output html is used, ACE writes an additional HTML file using the same prefix (for example public_my_table_diffs-20231027100000.html). The HTML diff report provides an easy-to-read, colour coded table of differences between nodes.

table-repair

Repairs table inconsistencies using a diff file.

Usage:

./ace table-repair [cluster] <schema.table> [flags]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.
• <schema.table>: The fully qualified name of the table to repair.

Flags:

Example:

./ace table-repair my-cluster public.my_table \
  --diff-file=public_my_table_diffs-20231027100000.json \
  --source-of-truth=n1

Repair reports (when requested) are written to reports/<YYYY-MM-DD>/repair_report_<HHMMSS.mmm>.json, while dry runs use the same directory with a dry_run_report_ prefix.

table-rerun

Re-runs a diff from a file to check for persistent differences.

Usage:

./ace table-rerun [flags] [cluster]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace table-rerun --diff-file=public_my_table_diffs-20231027100000.json --dbname=mydatabase my-cluster

If any rows still differ, table-rerun writes a fresh report named <schema>_<table>_rerun-diffs-<timestamp>.json; otherwise it logs a success message without producing a new file.

schema-diff

Compares schemas across nodes in a pgEdge cluster. By default, schema-diff performs a table-diff on every table in the schema and reports differences. Alternatively, schema-diff could also be used to compare if two or more nodes have the same set of tables, views, functions, and indices, which can be achieved by passing in ddl-only

Usage:

./ace schema-diff [flags] [cluster] <schema>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.
• <schema>: The name of the schema to compare.

Flags:

Example:

./ace schema-diff --dbname=mydatabase my-cluster public

Omit --ddl-only if you want to combine the command with --schedule --every=<duration> for recurring comparisons.

When --ddl-only is omitted, each table uses table-diff with the same block size, concurrency factor, compare-unit size, output format, and override behaviour supplied here.

repset-diff

Performs a table-diff on every table in a replication set and reports differences.

Usage:

./ace repset-diff [flags] [cluster] <repset>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.
• <repset>: The name of the replication set to compare.

Flags:

Example:

./ace repset-diff --dbname=mydatabase my-cluster my_repset

Add --schedule --every=<duration> to keep the sweep running until you stop the process.

Each table in the replication set is diffed with the same block size, concurrency factor, compare-unit size, output format, and override behaviour provided on the command line.

spock-diff

Compares spock metadata across cluster nodes.

Usage:

./ace spock-diff [flags] [cluster]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace spock-diff --dbname=mydatabase my-cluster

Merkle Tree Commands

mtree commands provide a more advanced and efficient way to compare tables using Merkle trees. This method is suitable for very large tables where a full table scan is too slow.

mtree init

Initialises the required database objects for Merkle tree operations on all nodes in a cluster. This includes creating a dedicated schema, tables for metadata, and setting up publications and replication slots for change data capture (CDC).

Usage:

./ace mtree init [flags] [cluster]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree init --dbname=mydatabase my-cluster

mtree build

Builds a Merkle tree for a specific table on all nodes in the cluster. This command should be run after mtree init.

Usage:

./ace mtree build [flags] [cluster] <schema.table>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree build --dbname=mydatabase my-cluster public.my_table

mtree table-diff

Compares the Merkle trees of a table across nodes to find inconsistencies. It generates a diff report similar to the standard table-diff command. By default, it first updates the Merkle trees with the latest changes using CDC before performing the diff.

Usage:

./ace mtree table-diff [flags] [cluster] <schema.table>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree table-diff --dbname=mydatabase my-cluster public.my_table

HTML output is also available via --output html; the command produces both JSON and HTML reports with matching timestamps.

mtree update

Manually triggers an update of a Merkle tree for a table using the captured changes from CDC. This can also be used to rebalance the tree.

Usage:

./ace mtree update [flags] [cluster] <schema.table>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree update --rebalance --dbname=mydatabase my-cluster public.my_table

mtree listen

Starts a long-running process that listens for database changes via CDC and automatically updates the Merkle trees for all tracked tables.

Usage:

./ace mtree listen [flags] [cluster]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree listen --dbname=mydatabase my-cluster

mtree teardown-table

Removes all database objects associated with a Merkle tree for a specific table. This includes the tree data, metadata, and removing the table from the CDC publication.

Usage:

./ace mtree teardown-table [flags] [cluster] <schema.table>

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree teardown-table --dbname=mydatabase my-cluster public.my_table

mtree teardown

Removes all database objects created by mtree init from all nodes in the cluster. This will drop the dedicated schema, all Merkle tree data, and stop CDC.

Usage:

./ace mtree teardown [flags] [cluster]

Arguments:

• [cluster]: Optional cluster override. When omitted, ACE uses the default_cluster from ace.yaml.

Flags:

Example:

./ace mtree teardown --dbname=mydatabase my-cluster