knaxly.dev / ferry

Ferry

A tiny local proxy you run so knaxly's browser SQL workbench, Quarry, can reach your own Postgres, MySQL and other databases.

Why you run it locally

Browsers cannot open raw TCP sockets, so a full live connection to a classic database needs a small bridge running next to your browser. That is the whole trade, stated plainly:

A full live connection to a TCP database requires you to run Ferry locally (one command). That is the cost of not uploading your credentials to us. Your connection string, queries and results stay on your machine.

Run it (one line)

Ferry prints a pairing token on startup. Copy that token into Quarry to connect.

NPX npx knaxly-ferry

DOCKER docker run --rm -p 127.0.0.1:8477:8477 knaxly-ferry

A single static binary (via node --sea or pkg) is planned so you will not even need Node or Docker. Source and build notes live in the proxy/ directory of the repo.

Security model

These are enforced in code, not just advice:

Localhost only. Ferry binds 127.0.0.1. It is a bridge for your own browser, on your own machine. Do not expose it to a network.
Origin locked. Requests are accepted only from https://knaxly.dev (plus localhost for development). Any other origin is rejected.
Token paired. A random pairing token is printed on startup and required on every request. No token, no answer (HTTP 401).
Target restricted. Ferry refuses to relay to arbitrary hosts. By default only local databases are reachable; you allowlist any others explicitly.
No credential logging. Connection strings, SQL text and query values are never written to logs. Logs contain only engine, row count and timing.

How it connects to Quarry

1 You start Ferry with one command. It listens on http://127.0.0.1:8477 and prints a pairing token.
2 Quarry, running in your browser on knaxly.dev, calls GET /health. When Ferry answers { ok: true, name: "ferry" }, Quarry shows "Connected to local proxy".
3 You paste the pairing token into Quarry and enter your database connection string. Both stay in the browser and go only to your local Ferry, never to knaxly's servers.
4 Each query is a POST to Ferry: { engine, connectionString, sql, params }. Ferry runs it through a native driver and returns { columns, rows, rowCount, durationMs }.

Engines

Enabled today, via mature native drivers:

Postgres · pg MySQL / MariaDB · mysql2

Scaffolded for a later release (recognized, not yet enabled):

SQL Server MongoDB Redis

Part of knaxly.dev · pairs with Quarry, the browser SQL workbench · source