Running the binary
Every command below callstimbal-connect. The service installs it in a fixed place, which is usually not on your PATH:
- Windows
- Linux
- macOS
In an elevated PowerShell:
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 askey_columnswhen you create a sync.[cursor]: the type can be a cursor column (integer, date or timestamp types, SQL Serverrowversion).- Warnings: no primary key on a table you want to upsert, or no cursor candidate at all.
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.
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:- From Timbal (API)
- On the server
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.Change the configuration from Timbal
Replace a server’sconnections 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.jsonandconnections.json. The local files are not changed, only shadowed.doctorwarns while a pushed configuration is active.
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.
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.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
- Uninstall from the server
- Revoke in Timbal
Without On Windows:Back up
--purge the service is removed but the configuration and credentials stay, so a reinstall can reuse the same identity. --purge deletes everything local.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.