Using a DuckDB extension Datapuddle doesn't include

Why some extensions are not included

Datapuddle compiles its DuckDB extensions into the app. Nothing is downloaded at runtime, which is what lets it work offline, pass the Mac App Store's rules and promise it makes no network request you did not ask for. The price is that an extension has to be built in to be available, and some cannot be. MySQL is the one people ask about most: its extension cannot be statically linked. Community extensions such as h3 are not included either.

The way around it: your own DuckDB, over Quack

Quack is DuckDB's own client and server protocol, and Datapuddle can connect to it. So you can run a copy of DuckDB yourself, load whatever extensions you like into it, and point Datapuddle at it. Your queries run on that DuckDB, with its extensions, and the results come back to Datapuddle's grid.

The server runs as an ordinary process on your Mac, so it can also read any file your user account can, without Datapuddle asking for access.

Step 1: get DuckDB 1.5.5

The server has to be DuckDB 1.5.5, the version built into Datapuddle. A DuckDB 2.0 server rejects Datapuddle's requests with a serialization error, and brew install duckdb now installs 2.0. The 1.5.5 command line is a single file:

curl -LO https://github.com/duckdb/duckdb/releases/download/v1.5.5/duckdb_cli-osx-universal.zip
unzip duckdb_cli-osx-universal.zip
./duckdb --version

The last line should print v1.5.5.

Step 2: load your extensions and start the server

Start ./duckdb, load what you need, then serve. With the community h3 extension, for example:

INSTALL quack; LOAD quack;
INSTALL h3 FROM community; LOAD h3;

CREATE VIEW cells AS
  SELECT name, h3_latlng_to_cell_string(lat, lon, 9) AS cell
  FROM 'places.csv';

CALL quack_serve('quack:localhost');

The last line prints an auth_token, a 32-character code. Copy it. The server runs for as long as that DuckDB window stays open, and listens only on this Mac.

For a fixed token instead of a new one each time, pass your own: CALL quack_serve('quack:localhost', token := '…').

Step 3: connect Datapuddle

1. Click + on the Connections section of the sidebar and choose Quack as the connection type.
2. Give it a name, such as srv. That name is how you refer to the server in SQL.
3. Host localhost. Leave the port empty for the default, 9494.
4. Paste the token, click Test, then Attach. The token is kept in the macOS Keychain.

Step 4: query it

Tables and views in the server's main database appear in the sidebar, and you query them by the connection's name:

SELECT * FROM srv.cells

The view's h3 function runs on the server, so Datapuddle never needs the extension itself. A view is the easy way to make any extension's output look like an ordinary table.

To run a query on the server without making a view, send it as text:

SELECT * FROM quack_query_by_name('srv',
  'SELECT h3_latlng_to_cell_string(40.7128, -74.0060, 9)')

Example: MySQL

On the server, attach the MySQL database and expose what you need as views in the main database:

INSTALL quack; LOAD quack;
INSTALL mysql; LOAD mysql;
ATTACH 'host=localhost user=me database=shop' AS shop (TYPE mysql, READ_ONLY);

CREATE VIEW orders AS SELECT * FROM shop.orders;

CALL quack_serve('quack:localhost');

Then SELECT * FROM srv.orders in Datapuddle. Views are needed because Datapuddle sees only the server's main database: a database attached on the server, like shop here, is not reachable as srv.shop.orders. The quack_query_by_name form above reaches it too.

A server on another machine

Quack in DuckDB 1.5.5 does not encrypt traffic itself, and DuckDB's own guidance is not to expose it directly to the internet. Put a reverse proxy that handles HTTPS, such as Caddy or nginx, in front of it. Datapuddle uses HTTPS for every host other than localhost. For a server on a private network without HTTPS, choose Plain HTTP in the connection sheet.

What to expect

• Version-locked. The server must match Datapuddle's DuckDB, 1.5.5 today. This does not unlock DuckDB 2.0 features.
• The server does the work. Queries run with the server's memory and the server's extensions. Results stream back to Datapuddle's grid as usual.
• Read-only is optional. Writes over Quack work, and the connection sheet has a read-only switch if you would rather not.

7-day trial, then $39.99 once · Apple silicon, macOS 26 or later

Datapuddle on the Mac App Store — 7 day trial, then $39.99 once. Apple silicon, macOS 26 or later. · Docs Guides · Home