Skip to main content
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 New 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 with Local File and Remote (Quack) connection typesDuckDB connection form with Local File and Remote (Quack) connection types

DuckDB connection form

​
What the file field accepts

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): 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

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:
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:

​
Sharing the file with another process

One process writes a DuckDB file at a time, and the lock lasts as long as the connection. While a tab is open on sales.duckdb, duckdb sales.duckdb in a terminal is refused, and so is a notebook, a dbt run, or a second TablePro window. Three ways out, in Options on the connection: Database ▸ Release File Lock hands it back now, without ending the session. The tabs, the schema cache and the row you were on all stay; the next query takes the file again. A release is refused, with the reason, while the session holds anything reopening would destroy: an open transaction, a temporary table or view, an attached database, or a changed setting. Commit the transaction or drop the temporary table and the release goes through. Read-only is not a way to keep writing from somewhere else. A read-write connection blocks every other process, read-only ones included; a read-only connection blocks writers. Two readers work, a reader and a writer do not. Releasing hands the file to whoever wants it next, which may not be you. A query run after another process has taken it fails until that process lets go; reconnect once it has.

​
Limitations

  • A DuckDB file takes one writer at a time. A connect against a file another process holds fails, naming that process and its process ID. Quit the duckdb CLI, the Python process or the other TablePro window first, or set Release the File Lock After.
  • 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.

​
… is using sales.duckdb

Another process holds the file. The message names it and its process ID. Quit it, or turn on Open the File Read-Only when the message says read-only would get in, which it does when the other process is itself a reader.

​
The database file is no longer at …

The file moved or was deleted while the connection was idle with its lock released. Point the connection at the new path, or restore the file, then reconnect.