Skip to main content
Two kinds of tasks live here: commands you run on the server, and actions you trigger from Timbal with the API. Server commands work even when the connector is offline; API actions need it online.

Running the binary

Every command below calls timbal-connect. The service installs it in a fixed place, which is usually not on your PATH:
In an elevated PowerShell:
Below, timbal-connect stands for that whole prefix.

Check the setup with doctor

doctor is a read-only preflight. It uses the same configuration lookup as the service, so it shows what the service will see. It exits with a non-zero code on failure, which makes it safe to script.
--table needs --connection. A bare name uses the default schema; schema.table splits on the first dot, so names with dots still work: --table "dbo.Cust. Ledger Entry" is schema dbo, table Cust. Ledger Entry. Marks next to a column:
  • [pk1], [pk2], …: primary-key columns, in order. Use them as key_columns when you create a sync.
  • [cursor]: the type can be a cursor column (integer, date or timestamp types, SQL Server rowversion).
  • Warnings: no primary key on a table you want to upsert, or no cursor candidate at all.
If Timbal has rebound the connector, doctor shows the address it will actually use, so it never reports the wrong one.

Run a query on the server

query runs one SQL batch against a connection and prints the result as tab-separated text (the rows on stdout, a (N rows...) summary on stderr). It goes through the same driver as ad-hoc queries from Timbal, read-only wrapper included, so it is the way to test exactly what a remote query would do.
The query setting in the connection file is not applied here: it limits Timbal, and whoever is logged in to the server already holds the connection string.

Manage the service

Set RUST_LOG=debug in the service’s environment for more detail.

Upgrade

The connector updates itself when Timbal pushes a new version. An update runs on trial: if the new binary can’t connect within its budget, the connector goes back to the previous one. You can also trigger it yourself:
Needs organization membership, and the connector online. It is refused while jobs are running.
The answer is dispatched: true, or dispatched: false if it already runs that version. Watch version in the connector’s details after it reconnects. See Update connector.
Some features need a minimum version:

Change the configuration from Timbal

Replace a server’s connections and filesystems from Timbal, without logging in to it: rotate a connection string, add a share, or change a query setting. It needs the connector online, the ConnectorsManage role and connector 0.1.28 or newer.
  • Each map is replaced as a whole. A map in the request replaces the server’s entire map; entries are never merged. A map you leave out keeps the local one. Send at least one.
  • The connector checks every entry, saves the result, and restarts by itself. It refuses while jobs are running.
  • On the next start the pushed maps win over environment variables, config.json and connections.json. The local files are not changed, only shadowed. doctor warns while a pushed configuration is active.
To go back to the files on the server:
Run it as the service user or root, then restart the service. The pushed configuration is stored next to the state file as config.override.json. It is refused while an update or rebind restart is in progress, a corrupt override is deleted when the connector starts, and there is no trial or automatic revert: to undo a bad push, push again or run local-config clear. If config.json sets both connections and connections_path, the connector fails to start before it reads the override.
This is the one action that sends connection strings, with their passwords, from Timbal to the server. They pass through Timbal’s control plane. If your rule is that credentials never leave the server, edit the files on the server by hand and don’t use this endpoint. See Push local config.

Move the connector to another environment

Point a running connector at a different Timbal address (for example from staging to production) without touching the server. The connector keeps its identity and credential, so the other environment must recognize it.
It needs the connector online, the ConnectorsManage role and connector 0.1.14 or newer, and answers 202 { "url", "dispatched": true }. It is refused while jobs are running (rebind refused: N job(s) in flight). The connector checks the address (wss:// and a *.timbal.ai host), saves it in rebind.json in its install folder, restarts, and is on trial: it must enroll at the new address within about 90 seconds per attempt, three attempts, or it goes back to the previous one. A wrong address can’t strand the server. Once it enrolls, the new address is confirmed and stays until the next rebind. The fleet list shows the connector going offline and coming back with the same id, and doctor on the server shows the effective address and whether it is on trial or confirmed. See Rebind connector.

Retire or revoke

Without --purge the service is removed but the configuration and credentials stay, so a reinstall can reuse the same identity. --purge deletes everything local.
On Windows:
Back up state.json before --purge if you want to keep the identity. If the binary is gone or service uninstall fails, remove the service by hand: Install on Windows or Install on Linux and macOS.

Settings and environment variables

For each setting, an environment variable wins over the configuration file (TIMBAL_CONNECT_CONFIG), which wins over the platform default. Windows services have no environment files, which is why config.json exists.

Next steps

Sync your data

One-off jobs, scheduled syncs and cursors.

Troubleshooting

Messages from the installer, doctor and the service log.