Skip to main content
Once a connection is configured, Timbal can read from it by name. This page shows how to explore a database through the connector and move tables into a knowledge base. Every request needs the connector online, Authorization: Bearer $API_KEY, and the ConnectorsManage role for anything that dispatches work. The commands below use $ORG_ID, $CONNECTOR_ID (from GET /orgs/$ORG_ID/connectors) and $KB_ID. They run against Timbal’s API, not on the server. All paths are under https://api.timbal.ai/orgs/$ORG_ID/connectors/$CONNECTOR_ID.

Find what to sync

1

List the connections

Only the names you configured on the server come back.
2

List the tables

approx_rows: -1 means the database has never analyzed the table.
3

Read the columns

Each column says whether it can be a cursor (cursor_candidate) and its place in the primary key (pk_position, starting at 1). Those two fields are everything you need to configure a sync.
4

Inspect one table in depth (optional)

Adds indexes, foreign keys, check constraints, comments and size. Needs connector 0.1.25.
doctor --connection erp --table dbo.Cust_Ledger_Entry gives the same answer on the server, without a live connection to Timbal. These calls time out after 15 seconds.

Try a query

Run one statement and see the result, to check a table before syncing it. It needs the ConnectorsManage role, connector 0.1.26 or newer, and the connection’s query setting to allow it, and every run is recorded in the audit log.
On MySQL and MariaDB send one statement. On PostgreSQL and SQL Server you can send several and get the last result set back (on PostgreSQL the last one that returns rows; SQL Server returns the true last set, even if empty). rows_affected counts changed rows for statements that return none on PostgreSQL and MySQL, and is null on SQL Server. See Run an ad-hoc query.

One-off job

A job copies a table once, starting now.
source.kind is postgres, sql_server or mysql. List recent jobs with GET /orgs/$ORG_ID/connectors/jobs?connector_id=$CONNECTOR_ID and stop one with POST .../jobs/$JOB_ID/stop. Stopping returns 200 { "job_id", "state" } and is safe to repeat. A job goes accepted, running, then completed, failed or stopped, and a finished job stays finished. Other fields: columns (a subset of columns; key_columns are added to it automatically), batch_rows (default 5000), and pacing to protect a busy source: batch_delay_ms and max_rows_per_sec (any source), max_dop and read_uncommitted (SQL Server only). See Create job.

Start from a point

cursor is an inclusive lower bound on the cursor column. It works with every mode: create a table with only the rows from a date on, or resume after a previous run.
Cursor values:

A table with no usable cursor

Leave out cursor_column and the job does one full scan, with no checkpoint: if it stops or fails, it starts over. Use it when nothing is monotonic, the only candidates are nullable, or a non-unique candidate has no primary key to break ties. Needs connector 0.1.25, and cursor can’t be set.

Scheduled sync

A sync stores the definition and runs it on an interval. Each run continues from where the last one landed.
  • The first run builds dest_table. Later runs append, or merge when key_columns is set.
  • start_cursor is a floor for the first run only.
  • interval_secs is the time between run starts, with a floor of about 30 seconds (any whole number of seconds up to 2147483647).
  • The sync is created, not run: wait for the next tick, or run it now.
  • List the syncs of a connector with GET /orgs/$ORG_ID/connectors/syncs?connector_id=$CONNECTOR_ID.

Adopt a table you already loaded

The usual path from “I copied these tables with one-off jobs” to “keep them fresh”: create the sync against the same dest_table. By default (existing_dest: "adopt") Timbal reads the largest cursor value in the table and continues from there, instead of loading it again.
Adoption is checked when you create the sync, not when it first runs: the cursor column must exist in the destination, and any key_columns you pass must match the table’s own primary key. Pass initial_cursor if the derived value is wrong (for example a job you stopped halfway), or existing_dest: "replace" to throw the table away and rebuild it. start_cursor is ignored when adopting, initial_cursor without an existing table is a 400, and an adopted table that is empty is simply built.

Run now

It runs exactly what the next tick would, restarts the interval, and skips any failure backoff, so it doubles as “I fixed it, try again now”. The sync must be enabled (sync_disabled) and have no run in progress (run_active; stop the job first). Needs connector 0.1.30.

Pause, change, delete

PATCH and DELETE answer 204. PATCH only takes enabled and interval_secs. To change the source or destination, delete the sync and create it again against the same dest_table: it adopts the rows already there.

Full-refresh sync

Leave out source.cursor_column and the sync is no longer incremental: every run reads the whole table and rebuilds dest_table. Use it for tables that are updated or deleted in place with nothing recording it. An incremental sync would keep appending and never notice a deletion.
  • The whole table crosses the connection every interval_secs. Size the interval to the table, and prefer an incremental sync whenever there is a usable cursor.
  • While it runs, the destination is rebuilt in place: a query at that moment sees a partial table, and a run that fails halfway leaves one until the next run completes.
  • If the source is emptied, the destination is emptied too.
  • start_cursor, initial_cursor and existing_dest: "adopt" are refused: there is nowhere to continue from. existing_dest: "replace" is accepted and changes nothing. key_columns keep the primary key on each rebuild, and pacing helps with large tables. Needs connector 0.1.25.

Keys and merging

key_columns are the destination’s primary key, in order. Take them from pk_position in the column list.
  • With keys, the first run creates a keyed table and later runs merge: a row that comes again overwrites its previous version.
  • Without keys, the table is append-only.
  • upsert needs keys. They’re also strongly recommended whenever the cursor isn’t unique on its own.

Choosing a cursor

The connector reads in batches, ordered by the cursor and then the key, and remembers the last row it landed. Every run after the first resumes inclusively from the saved checkpoint. It first removes the rows at or after it (for a keyset cursor, the exact matching row), then reads again from it, so a crash or restart never leaves duplicates. Keyed tables merge on every batch anyway. Dates and times are converted to what the column’s type accepts: fractions of a second are trimmed to the type’s precision, and time-zone suffixes are removed where the type can’t hold them. That means an ISO value such as 2026-06-01T00:00:00Z works as a floor on every database. Connector 0.1.24 or newer: older versions failed on legacy datetime columns in SQL Server, and silently matched no rows on MySQL.

Watch a sync

Failures back off. A run that fails itself (a source SQL error, not a disconnect or a stop) doubles the wait before the next try, up to an hour or the interval, whichever is larger. After 10 failures in a row the sync is disabled and disabled_reason says why. A completed run resets the count, and so does enabling the sync again. Fix the cause, then PATCH {"enabled": true} (this also clears disabled_reason) and run it now. Trying to run a disabled sync returns sync_disabled with the reason.

Common refusals

Next steps

File shares in Timbal

Explore folders and copy files into a knowledge base.

Connect your IDE

Browse schemas and run bounded SQL from Cursor.