Quickstart

From a running install to a first working bridge: create the operator account, connect a database, build a bridge from one of its tables, run it, and read the delivery timeline. It assumes you have already run syncle up — if not, start with the installation page.

Create the operator account

The first time Syncle starts, the API writes a one-time setup token to its data directory and prints it in its logs. syncle up (and syncle open) read that token off the container and open the interface with it in the URL fragment, as http://localhost:3002/#setup-token=<token>. A fragment never leaves the browser, so the token appears in no request log; the setup form reads it, shows a banner confirming you are verified as this server's operator, and strips it from the address bar.

The form asks for a username (at least 3 characters) and a password (at least 8, entered twice). Submitting it creates the single operator account — there is no signup and no second account — and the API deletes the token the moment the account exists.

If you open Syncle from a different device, the token is not prefilled. Print it and paste it into the form by hand:

syncle logs api

Connect a database

Databases live behind the Data sources button in the sidebar — a full-screen overlay for connecting databases, browsing tables and managing schema. Add a connection: a display name, an engine — PostgreSQL, MySQL/MariaDB, SQLite, MongoDB or Redis — and host, port, user and password. A Use TLS / SSL toggle covers encrypted connections, and an SSH tunnel option reaches a database through a jump host, authenticated by password or PEM private key. The Test button tries the connection before you save it; credentials are encrypted at rest and come back to the browser redacted.

Your database stays where it is — Syncle connects out to it. Once saved, the connection's tables appear in the schema tree, and the overlay's Data, Structure, Query and Diagram tabs let you look around; the workbench page covers those in full.

Create a bridge

Every table in the schema tree has a Create bridge action in its table menu, which opens the bridge builder seeded with that table. The builder is one full-screen form: source, trigger, payload, destination, delivery settings.

In the source table's preview, click column headers to include or exclude columns; the sample payload under What gets sent updates as you do. Under Trigger, choose One-time job — streams the rows once when run — or Live bridge, which delivers new rows as they appear, either by polling on a cursor or by event-based CDC from the database's change log. For a first bridge, a one-time job shows the whole loop in a single run. CDC has per-engine prerequisites: the builder's Check readiness button either reports that the source is ready ("we'll auto-create the publication & slot on start") or lists the setup steps still needed, which the CDC page explains.

Under Destination, point the bridge at an HTTP endpoint (URL and method, with optional bearer-token or custom-header auth) or at one or more target databases — pick the target connection and table, existing or new, and a write mode of Upsert or Insert. Cross-engine targets work, and Syncle can create the target table from the source's shape. Write modes, column mapping and the delivery knobs are covered on the bridges page.

Run it and read the timeline

On the bridge's panel, a one-time job has a Run job button; a live bridge has Start listening and Stop listening. Either way, a live timeline colours every delivery: green for synced, red for failed, amber for skipped, slate for queued. Clicking a cell shows the exact row that was written, the result, the timing, and any error, and failed deliveries can be retried in place.

The log has three views: records (the synced rows as a table), feed (newest first, useful while a live bridge is listening), and map (one cell per delivery, for progress at a glance). Jobs, statuses and what the guarantees actually are belong to the bridges page.

Testing HTTP destinations

The product repository ships a small echo receiver for trying HTTP destinations without a real endpoint. From a checkout:

pnpm dev:receiver
# Receiver listening on http://localhost:4990

It logs every request's method, URL and body — JSON is pretty-printed — and answers everything with {"ok":true}. Point a bridge's HTTP destination at http://localhost:4990 and each delivery prints in the terminal as it lands. That address works when the API can reach your machine's localhost — running from source it can; from the Docker install, localhost inside the API container is the container itself, not your machine.

Where next

How bridges work explains trigger modes, delivery guarantees and the tuning knobs; CDC setup walks the per-engine prerequisites for real-time bridges; and the workbench page covers everything else behind the Data sources button.