DuckDB

Open local DuckDB files or connect to a remote DuckDB server over Quack

Pick a .duckdb file to open a database, or a .parquet, .csv, .tsv, .json or .ndjson file to read it where it sits. DuckDB 1.5.2 is compiled into the driver, so nothing runs as a server unless you point the connection at one.

The driver is not in the app. Picking in the Choose a Database sheet offers the download before the form opens, and opening a saved connection installs it without asking. Settings > Plugins > Browse > installs it up front. See Plugins.

Quick setup

1. Create the connection

   Click Create Connection… or press Cmd+N, then choose DuckDB.

2. Choose a file

   Leave Connection Type on Local File and click Browse…. Type :memory: in the field instead for a database that lasts as long as the session.

3. Connect

   Click Save & Connect.

DuckDB connection form

What the file field accepts

Path	What you get
.duckdb, .ddb	The database in that file. A path that does not exist yet is created
.parquet, .csv, .tsv, .json, .ndjson	An in-memory database holding two read-only views over the file, one named file and one named after the file. A path that does not exist is reported instead of created
:memory:	An empty database, discarded on disconnect

In Local File mode the path is the whole connection, and it is required; the form shows no host, port or Database field.

Double-click a .duckdb or .ddb file in Finder to open it here. .parquet files list TablePro under Open With rather than taking the association; to make a double-click open them here, select one in Finder, press Cmd+I, set Open with to TablePro, and click Change All…. .csv, .tsv, .json and .ndjson open from the connection form only.

A DuckDB database carries DUCK eight bytes in, so a database opens under any name: drag warehouse.db onto a window and it reaches this driver rather than SQLite. The data formats need their extension either way, because the reader is chosen from it. Installing the plugin is offered first when it is not already there.

Remote (Quack)

Quack is DuckDB’s client-server protocol, served by quack_serve. Set Connection Type to Remote (Quack, experimental):

Field	Value
Host	Server address. Required
Port	9494 by default
Token	The token the server was started with
Database Alias	The name the remote is attached under. Pre-filled with remotedb

Save & Connect attaches the remote to an in-memory DuckDB. Reach it through the alias: SELECT * FROM remotedb.main.orders.

The quack extension is not linked into the macOS build. DuckDB downloads it from extensions.duckdb.org on the first remote connect and caches it under ~/.duckdb, so that one connect needs to reach that host.

Connection URL

duckdb:///path/to/database.duckdb
quack://host:9494/alias

See Connection URL Reference for all parameters.

Databases and schemas

A connection opens one database named after the file: analytics.duckdb becomes analytics, schema main. ATTACH a second file and it joins the sidebar as a sibling database after a refresh:

ATTACH 'warehouse.duckdb' AS warehouse;

Press Cmd+K to move between them, in place, with no reconnect. DuckDB does not persist attachments, so a reconnect starts again from the one file. system and temp are hidden, and with them information_schema and pg_catalog.

Any connection can also read a file straight from SQL:

SELECT * FROM 'data.csv';
SELECT * FROM read_parquet('analytics.parquet');

Limitations

• A DuckDB file takes one writer at a time. A connect against a file another process holds fails, naming that process. Quit the duckdb CLI, the Python process or the other TablePro window first.
• A data file opened through Browse… is read-only, and the file on disk is left byte for byte identical. To change its contents, open a .duckdb database and run CREATE TABLE t AS SELECT * FROM 'data.parquet'.
• Remote (Quack) lists no tables in the sidebar. Write them out by name through the alias.
• No SSL/TLS section and no SSH tunnel. The engine is in-process; see SSL/TLS.
• No creating or dropping a database. ATTACH is the way to reach a second file.

Troubleshooting

No file at …

A data-file path that is not there. Only .duckdb and .ddb are created on demand. Re-pick the file with Browse….

DuckDB opened the file but reported no catalog to browse

The file opened and exposed nothing to list. Check that it is a DuckDB database and not a file with a borrowed extension.

Port must be a number between 1 and 65535

Port holds something else. The Quack default is 9494.

Related

• TablePro for iPhone and iPad, where DuckDB opens a file picked through the Files app
• Import & Export