Skip to main content
Get Started
Documentation

Connect Tractorscope to a DuckDB server with quack

DuckDB is usually something you run beside your code — a file on disk, or an in-process engine with no server to point anything at. The quack protocol changes that: a DuckDB instance can listen on a port and answer queries from other DuckDB clients over HTTP.
Tractorscope connects to a DuckDB server that way. Choose DuckDB (Quack) as the database type and fill in three fields.

What you need

  • Quack Host — the hostname of your DuckDB server, without the
    quack:
    prefix. For example
    duckdb-f70db505b7.fly.dev
    .
  • Port — defaults to
    443
    .
  • Quack Token — the access token your server was started with. It is encrypted before it is stored, and it is never sent back to the browser.
  • SSL — leave this on unless your server deliberately serves plain HTTP. With SSL on, Tractorscope connects over HTTPS.
There is no database name, user, or password to supply. A quack connection points at a server rather than at a single catalog, so Tractorscope lists whatever tables that server exposes.

Starting a server to connect to

On the DuckDB instance you want to expose, load the extension and call
quack_serve
:
INSTALL quack;
LOAD quack;

CALL quack_serve('quack:0.0.0.0:443', token = 'your-token');
INSTALL quack;
LOAD quack;

CALL quack_serve('quack:0.0.0.0:443', token = 'your-token');
The token you pass here is the one you give Tractorscope. If you leave
token
unset, DuckDB generates one and prints it.
The quack remote protocol requires DuckDB 1.5 or newer. On older versions
INSTALL quack
appears to succeed but installs an unrelated demo extension that has no
quack_serve
in it, so check your version first if the call is not found.

How tables appear

Tables are listed as
schema.table
—
main.orders
,
sales.invoices
— and that is how you should reference them in chart queries. The data browser shows the qualified name, so copying it from there always works.
Each query is sent to the server as a single statement. Write chart queries without a trailing semicolon, and do not send several statements at once.

Permissions

Tractorscope only ever reads. Write statements are rejected before they are sent, and the connection is used for queries, schema listing, and row counts.
Because the token is the whole of the authentication, treat it like a password: give Tractorscope a token scoped to the data you want visible, and rotate it by updating the connection.

Related docs