Getting started

On this page, you run a reconciliation on your own machine. You see it report a mismatch, and you narrow the mismatch down to the two rows that cause it. The walkthrough uses a self-contained dataset, so you need no warehouse and no credentials. At the end, a small change points it at your own databases.

Install the CLI

Homebrew
Binary
Windows
Docker

brew install getsynq/tap/synq-recon

To update, run brew upgrade synq-recon. Homebrew is for macOS only. See Command-line tools for the other ways to install.

Every published binary runs DuckDB, which is what the walkthrough below uses so it needs no warehouse and no credentials.

The archive file name contains the version, so you must name it. The first line reads the version from the releases page:

VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' \
  https://github.com/getsynq/synq-recon/releases/latest | sed 's#.*/v##')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')          # darwin or linux
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')

curl -fL "https://github.com/getsynq/synq-recon/releases/download/v${VERSION}/synq-recon_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | tar -xz
sudo mv synq-recon /usr/local/bin/

Builds are published for macOS and Linux on both amd64 and arm64, and for Windows on amd64 (see the Windows tab). Each archive also carries the operating guide and the example suites, and every release ships a checksums.txt you can verify with sha256sum -c checksums.txt --ignore-missing.

Every published binary runs DuckDB, which is what the walkthrough below uses so it needs no warehouse and no credentials.

On macOS a downloaded binary may be quarantined. If it refuses to start, xattr -d com.apple.quarantine /usr/local/bin/synq-recon clears the flag.To update a binary that you installed this way, run synq-recon upgrade. It downloads the latest release, verifies it against checksums.txt and replaces the binary. synq-recon upgrade --check shows what it would do.

Download synq-recon_<version>_windows_amd64.zip from the releases page, then in PowerShell:

Expand-Archive synq-recon_<version>_windows_amd64.zip -DestinationPath "$env:LOCALAPPDATA\synq-recon"
$env:Path += ";$env:LOCALAPPDATA\synq-recon"   # this session; add it to your user PATH to keep it
synq-recon --version

The Windows build runs DuckDB too, so the walkthrough’s suites run there. Its synq-recon commands work as written in PowerShell, except the last one, which is a bash pipeline into jq.

Get-FileHash -Algorithm SHA256 <archive> gives the value to compare against the release’s checksums.txt.

docker pull europe-docker.pkg.dev/synq-cicd-public/synq-public/synq-recon:latest

Run it with your working directory mounted, so it can read your suite file:

docker run --rm -v "$PWD:/work" -w /work \
  europe-docker.pkg.dev/synq-cicd-public/synq-public/synq-recon:latest \
  synq-recon check-config suite.yaml

The image runs DuckDB. The walkthrough below uses DuckDB, so it needs no warehouse. If a duckdb: connection fails with a driver error, your image is older than DuckDB support. Pull :latest.

Check that it runs:

synq-recon --help

You must sign in only to save suites to your workspace or to start backend runs. A local run needs no Coalesce Quality credentials.

synq-recon auth login
synq-recon auth whoami

auth whoami prints the workspace of your credential. Always read that line. It is the only thing that decides which workspace a command writes to.

Describe what to compare

A suite is a YAML file that holds the connections and the reconciliations. Save this as quickstart.yaml:

quickstart.yaml

# yaml-language-server: $schema=https://schemas.synq.io/synq-recon/v1/config.schema.json

name: quickstart
title: Quickstart

connections:
  local:
    duckdb:
      database: ":memory:"

# Stands in for two real systems: an application database and the warehouse
# copy of it. The copy is missing one order and has the wrong amount on another.
setup:
  local:
    - |
      CREATE TABLE app_orders AS
      SELECT i AS order_id, 'CUST-' || (i % 7) AS customer_id, i * 10.0 AS amount
      FROM generate_series(1, 1000) AS t(i)
    - |
      CREATE TABLE warehouse_orders AS
      SELECT order_id, customer_id,
             CASE WHEN order_id = 617 THEN amount + 5 ELSE amount END AS amount
      FROM app_orders
      WHERE order_id <> 384

reconciliations:
  orders:
    title: Orders (application vs warehouse)
    source:
      connection: local
      table: app_orders
    target:
      connection: local
      table: warehouse_orders
    key_columns: [order_id]
    mode: row_checksum
    bisection:
      factor: 10
      threshold: 10

That first line points your editor at the published JSON schema, which gives you completion and inline validation for every field. Keep it at the top of every suite you write.

The bisection block is tuned small here so the drill-down has something to do on a thousand rows. On real tables the defaults are the right starting point.

Validate before you run

synq-recon check-config quickstart.yaml

Checking configuration: quickstart.yaml

Configuration Summary
=====================

Connections (1):
  - local (duckdb)

Reconciliations (1):
  - orders
    Source: local
    Target: local
    Key Column(s): order_id
    Mode: row_checksum
    Bisection: factor=10, threshold=10

Configuration check passed!

This costs nothing and touches no database. Add --db to also connect, run every query through the database’s planner, and report table sizes, indexes and a suggested key column:

synq-recon check-config quickstart.yaml --db

--db does not run the setup: SQL of the suite, so for this walkthrough it reports that app_orders does not exist. This is expected. The setup SQL makes the tables when the reconciliation runs.

Compare

synq-recon run-check quickstart.yaml --no-report

Coalesce Quality Reconciliation - Quick Check
============================================

Reconciliation: Orders (application vs warehouse) (orders)
Mode: row_checksum
Duration: 6ms

             Source              Target
Row Count    1,000               999

Status: MISMATCH
  - Source has 1 more rows than target

Hint: Run 'synq-recon run-drill <config> --include orders' to locate differences.

Two queries, one per side, tell you that the datasets do not agree. If they agreed, this would be the full run.

The command exits 1. For a comparison, a non-zero exit means “differences found”, which is a result rather than a failure. Exit codes has the full list.

--no-report keeps the run entirely local. Without it, a run reports its results to your workspace whenever it can find a credential, so they show up in the app alongside backend runs.

Locate the difference

synq-recon run quickstart.yaml --auto-drill --no-report

Depth 0: Segment [*, *)
  Source: 1,000 rows, checksum: -2052783606565609
  Target: 999 rows, checksum: -2210053578859533
  Status: MISMATCH -> drilling down (20/1,000 rows in mismatched segments)
  Depth 1: Segment [301, 401)
    Source: 100 rows, checksum: -167029730887454
    Target: 99 rows, checksum: -295596598382435
    Status: MISMATCH -> drilling down (10/100 rows in mismatched segments)
    Depth 2: Segment [381, 391)
      Source: 10 rows, checksum: 330886401684630
      Target: 9 rows, checksum: 202319534189649
      Status: MISMATCH (leaf: threshold_reached)
  Depth 1: Segment [601, 701)
    Source: 100 rows, checksum: -683539572079355
    Target: 100 rows, checksum: -712242676878298
    Status: MISMATCH -> drilling down (10/100 rows in mismatched segments)
    Depth 2: Segment [611, 621)
      Source: 10 rows, checksum: -381158226855223
      Target: 10 rows, checksum: -409861331654166
      Status: MISMATCH (leaf: threshold_reached)

Summary
-------
Segments processed: 33
Mismatch leaves: 2
Max depth reached: 2
Duration: 26ms

Read that from the top. The whole dataset disagrees, so it is split into ten segments; eight of them match on the first comparison and are never looked at again. The two that differ get split again, and the run stops with two ten-row windows to inspect. Look at the shape of each finding. The segment around order 384 has one row less on the target: a row is missing. The segment around order 617 has the same count but a different checksum: a value changed. You did not read a row value yet.

The drill-down compared 33 segments with 17 queries to find two bad rows in a thousand. The number of queries grows with the logarithm of the row count, so the saving grows with the table.

Get the rows

Every mismatch leaf comes with ready-to-run SQL for both sides:

synq-recon run-drill quickstart.yaml --no-report -o json 2>/dev/null \
  | jq -r '.investigation_queries[] | .source_query, .target_query, "--"'

Run these queries on the two databases to see the rows. This is the first time that row values are read: by you, in your SQL client, for ten rows and not for a million.

Redirect logs with 2>/dev/null, never 2>&1. Logs go to stderr and results to stdout; merging them makes -o json unparseable.

Point it at your own databases

Swap the connections: block for the real thing, drop the setup: block, and name your tables. Nothing else changes:

suite.yaml

connections:
  app:
    postgres:
      host: db.internal
      port: 5432
      database: payments
      username: ${PG_USER}
      password: ${PG_PASSWORD}
  warehouse:
    snowflake:
      account: myorg.us-east-1
      warehouse: COMPUTE_WH
      role: ANALYST
      username: ${SF_USER}
      password: ${SF_PASSWORD}
      databases: [ANALYTICS]

reconciliations:
  orders:
    title: Orders (application vs warehouse)
    source:
      connection: app
      table: public.orders
    target:
      connection: warehouse
      table: ANALYTICS.PUBLIC.ORDERS
    key_columns: [order_id]
    mode: row_checksum

Then run the same four commands. Two things to do before you trust the result:

Keep the credentials out of the file. Move the connections: block to a git-ignored .connections.yaml. The CLI finds it automatically. See keep credentials out of the suite.
Run check-config --db. It checks every connection and query, and warns if your key column has no index. Without an index, a drill-down can take minutes and not seconds.

Next steps

Authoring suites

Datasets, column selection, key columns, and the validation loop in full.

Time windows and cutoffs

Comparing two live systems? Read this before you trust a mismatch.

Workspace suites

Save the suite, start a backend run, put it on a schedule.

CLI reference

Every command, argument and flag, generated from the CLI itself.

Get Started

Alerts

Monitors

Monitors Types

Reconciliations

Data Products

Scout AI

Ownership

Incidents

Analytics

Query activity

Lineage

BI Integrations

Data Warehouse Integrations

Transactional databases

Code Integrations

dbt Integrations

SQLMesh Integrations

Coalesce Integrations

Orchestration Tool Integrations

Alerting Integrations

Catalogs

Google Cloud Integrations

Admin

Security

Support

Developer API

Install the CLI

Describe what to compare

Validate before you run

Compare

Locate the difference

Get the rows

Point it at your own databases

Next steps

Authoring suites

Time windows and cutoffs

Workspace suites

CLI reference

​Install the CLI

​Sign in

​Describe what to compare

​Validate before you run

​Compare

​Locate the difference

​Get the rows

​Point it at your own databases

​Next steps

Authoring suites

Time windows and cutoffs

Workspace suites

CLI reference

Install the CLI

Sign in

Describe what to compare

Validate before you run

Compare

Locate the difference

Get the rows

Point it at your own databases

Next steps