CHANGE_ME, and a step tells you where to replace it.
Before you start
- Network. The server needs outbound TCP 443 to
api.timbal.ai. Check it first with Network requirements. - Permissions in Timbal. Creating tokens and running queries needs the ConnectorsManage role. Browsing schemas and folders only needs organization membership.
$ORG_IDand$API_KEY. Your organization id and an API key. Set them as environment variables on the machine where you run thecurlcommands. The key is organization-wide: treat it like a password.
What the steps do
Why a read-only login?
Why a read-only login?
The connector reads tables, so it needs
SELECT and nothing else. The query setting in the connection file limits what Timbal can ask for, and the server always has the last word, but a login that can only read is the stronger limit. It also keeps working if someone changes the setting by mistake.Why check the port before writing the configuration?
Why check the port before writing the configuration?
doctor reports a failed connection with the driver’s message, which can be hard to read. A blocked port is the most common cause, and Test-NetConnection or nc shows it in a second.connections.json or config.json?
connections.json or config.json?
Both work.
connections.json has been there from the start and keeps credentials apart from the control-plane settings. Putting connections inside config.json (from connector 0.1.27) keeps everything in one file. File shares always go in config.json. If both are set, the inline connections win and connections.json is ignored: see Where the connector looks.What stays on the server?
What stays on the server?
Connection strings, passwords and real folder paths. The one exception is configuration you push from Timbal yourself, which carries the connection strings down to the server. Timbal otherwise only receives the names you chose (
connection_ref and filesystem_ref), table and column metadata, and the rows or files you ask it to extract.Next steps
Configure connections
Every field and every option, with reference examples.
Operate the connector
doctor, query, upgrades, remote configuration and revoking.
Sync your data
One-off jobs, scheduled syncs and cursors.
Connect your IDE
Browse schemas and run bounded SQL from Cursor.