An admin screen may look at any table of any service - through glass. Read only, a timeout, caps, a log line, one at a time, and the glass is shut until someone opens it on purpose.

👋 Hi, I'm Anton - a software engineer. These days I work on a platform: contracts, generated code, data paths and the tooling around them. Running notes live on my GitHub: github.com/brilliant-almazov.

The guarded query is built into the shared library and is off by default. No service imports it directly yet; everything below describes what is built, not how much it is used.

This is part 2 of the series on what a shared platform does for every service, told as a zoo. Maybe you already do it better, maybe you'd do it another way - this is how it is going, and where it stops.

In real life

Ember, the small dragon of our zoo, guards the gold. That is what dragons do, and in our zoo the gold is the data: every resident keeps its own pile in its own cave, and nobody else is supposed to touch it.

Nora, the keeper, wants to count the coins. Not take them - just count. "Give me a key, I'll just count." Ember's answer is the answer every database owner has given: "Nobody touches my gold." And Ember is right. A key does not know the difference between counting and carrying.

So the zoo puts a viewing window into the cave wall. Pickle presses a nose to the glass and is delighted: "I can see every coin!" Biscuit tries to pass a bone through - "can I feed it?" - and learns what glass is for: look only. And when too many faces press against the window at once, Pip does the one thing that keeps the dragon calm: "Full. No waiting. Come back later."

A four-panel comic: Nora asks the dragon on its gold for a key to count, the dragon refuses; Pickle at a big window sees every coin; Biscuit asks to pass a bone through the glass and Ember says look only; Miso wants to wait at a full window and Pip says no waiting, come back later

That is the whole part in four panels. The admin screen can look at any table - through the service, through glass, one look at a time.

The key nobody should have

Admin screens want data. A list of records, a count, a join to check one thing on a Tuesday. The easy answer is a database address per service in the admin's configuration, and from then on the admin holds a key to every cave. A key does not know the difference between a SELECT and an UPDATE, does not know when to stop, and leaves no trace in the service that owns the data.

The library's answer is a guarded query that lives inside the service. The admin screen asks the service; the service runs the query on its own terms; the database address never leaves the resident. The line in the library's description says it plainly: the admin gets the schema and any selection through the service, not through a direct database address.

Three tiles with faces: an admin screen, the service proud in the middle, its small pool happy; labels read no address and read only; pills read built, and off by default

Six panes of glass

Every query that comes through the window passes the same guards.

A waffle of eight cells: six green cells with checks - six guards on every query; one amber cell - one switch, off by default; one red cell with a cross - one refusal, busy, at once; Ember says look all you like; a pill reads built

Guard What it stops
a read-only transaction any write, however it is spelled
a statement timeout a query that would run all afternoon
a row cap a result that would not fit on any screen
a byte cap a few rows with huge values
its own small pool, or a replica the window starving the service's real work
one log line per query a look nobody can account for later

The settings, as a form - the names here are illustrative, the shape is what the library takes:

data_query: enabled: false # off by default  concurrency: <n> # over it: busy at once, no waiting  pool: <small own pool | replica> statement_timeout: <duration> max_rows: <n> max_bytes: <n> # every query: a read-only transaction, the timeout, one log line 

A dark card with the window's settings as a form; the line enabled false, off by default, is highlighted; pills read built, and off by default

Two choices in that form matter more than the rest.

Off by default. The window is a wall until someone turns it into glass on purpose, for one service, with a switch in that service's environment. A new service does not get an open window because it was born.

Busy means no. When the number of running queries reaches the concurrency limit, the next one is refused at once - not queued, not made to wait. A queue in front of a database is a queue that grows exactly when the database is slow. Refusing at once keeps the cost of a look bounded and moves the waiting to the person who can decide whether to come back.

An animation: an admin screen sends a read query to the service, which sets read only and the timeout and reads rows under the cap from the small pool; then a second query arrives while the first is running, the service turns angry and refuses it at once

A key versus a window

Before and after: a key - everything, any table, any statement; unseen, no line in any log - and a window - read only, with a timeout and caps; logged, one line per query

The difference is not only safety. A key spreads knowledge of a service's database into every tool that holds it: the address, the credentials, the shape of the tables. A window keeps that knowledge in the service, which already describes its own tables through the sign from the previous part. The admin screen asks "what do you have" and "show me" - and both answers come from the resident.

Who looks through it yet

Columns: files about 40, commits since October 2, services using it 0; Ember, bored, says nobody at the glass yet; pills read built, and barely used yet

The window is new. The package is small - around forty files - and it reached the library late in October. No service imports it directly, and on every server it is off unless switched on. That is the state I can describe: the glass is installed, the switch is in the off position, and the first visitor is the admin screen it was built for.

What went wrong

The thing this part answers is a habit rather than an incident: when a screen needs data from a service, the fastest path is always a direct database address, and every such shortcut is a key handed out for good. The window exists because "just give the admin read access" kept being the easiest answer, and easy answers are the ones that stay.

The second lesson is in the busy refusal. A first instinct for "too many queries" is a queue. A queue in front of a struggling database makes everything slower at the worst moment, so the library refuses instead and lets the caller decide.

Service tiles with faces: the admin screen happy, the service proud, the small pool happy; the switch bored, a busy query angry, the log happy; pills read built, and off by default, barely used yet

What I do not claim

  • Not that any service runs with the window open today. It is off by default and imported by none directly.
  • Not that the guards are measured under load. They are built.
  • Not that read only is enough on its own. It is one guard of six, on purpose.
  • Not the exact names of the settings. The form above shows the shape.

What of this is method

  • Look through the owner, not around it. The service holds its database address; tools ask the service.
  • Every look is bounded and written down. Read only, a timeout, caps, a log line.
  • Shut until opened, busy means no. Off by default; over the limit, refuse at once.

Zoo keeping, built in - Part 2. Next: The Error That Escaped Without A Collar.

If your admin tools hold database addresses, how many caves do they have keys to? If you route queries through the service, what guards did you put on the glass? If you queue queries when busy, what happens to the queue when the database is slow? Who in your zoo has a key that should be a window?