nordisk/skade

One catalog, three doors — for idiots

Class: idiot · Function axis: f0 (zero → serving the catalog on a wire). No prior knowledge assumed. The fuller version is in tri-modal-catalog-guide.md; if you have never used skade at all, read for-idiots.md first.

The idea in one sentence

skade keeps the list of your data tables in one small file, and you can reach that one file through three different doors depending on who is knocking.

The three doors

1. Embedded — no door at all. Your own Rust program links skade and is in the same room as the file. Fastest possible: no network, no waiting. Millions of look-ups per second.
2. REST — the standard, everyone-speaks-it door (HTTP + JSON). Tools like Spark, PyIceberg, DuckDB and Trino already know how to knock here.
3. gRPC — the fast, binary door (HTTP/2 + protobuf). Our own Rust programs use this when they are on another machine and want speed. Almost no other catalog in the world has a door like this.

The important part: it is the SAME file behind all three doors. Put a table in through the gRPC door, and someone at the REST door sees it immediately. There is no copying and no "which one is the real one?" — there is only one.

Turning the doors on

One command opens a server with whichever doors you ask for:

$ skade-katalog serve --warehouse ./data --rest 0.0.0.0:8181 --grpc 0.0.0.0:8182

• --warehouse ./data — where your table files live.
• --rest … — open the REST door on that address.
• --grpc … — open the gRPC door on that address.

Leave one out to open just the other. The program that runs this holds the key: it is the one allowed to write, so two writers can never trample each other.

Which door should I use?

• Writing a Rust service that lives next to the data? Embedded — skip the doors.
• A Python/Spark/Java tool needs the tables? REST.
• Another one of our Rust services, over the network, wants it fast? gRPC.

The one safety rule you get for free

If two people try to change the same table at once, the second one is politely told "someone moved this while you were looking — try again" (a conflict). You do not have to do anything; skade checks it every time, on every door.