What TERSL/DB is

Overview#

TERSL/DB is a hosted service that stores TERSL documents and lets agents and people read and write them over HTTP. Each stored document is called a namespace. Every change to a namespace is kept as an entry in its history, and the history can be checked for tampering. Access is granted per API key and per path inside the document, so one agent can be allowed to append to one branch of a namespace while another may only read a different branch.

This page introduces the objects TERSL/DB works with and what you do with each of them. After reading it you will know which page of this section to read next for the task in front of you.

The objects#

An account is what you sign up for. It owns everything else: its namespaces, its API keys, the portal users who administer it, and a plan that sets its limits. Two accounts never see each other's data, and a key belongs to exactly one account.

A namespace is one TERSL document. The service gives it a seven-character name such as 7QK4M2C, drawn from the digits and the capital letters except I, L, O and U, never starting with 0, and never issued again once the namespace is deleted. The HTTP API addresses a namespace by this name, which the portal shows as the Namespace Id; you also give it a display name, which is what the portal lists. A namespace holds state in the same shape as any TERSL document: containers, objects, attributes and text.

A key is the credential an agent or program presents on every request. It has the form tsk_ followed by a key id and a secret, and it is shown once when it is issued. A key by itself reaches nothing: what it may do in a namespace is decided by that namespace's grants.

The grants for a namespace live in its companion document, {ns}_meta, under the # Access section. Each key named there receives rights (read, add, modify, remove, append, reorder, rename, history, or all) anchored at paths in the namespace. You edit this document on the portal's Grants page. Because the grants are themselves a TERSL document with a history, you can find out which grants were in force at any earlier point.

The record is a namespace's history: one entry per committed write, numbered by a change sequence number (CSN) that starts at 1 and increases by one per write. Each entry keeps the declaration text exactly as it was sent, with the time, the key that sent it, and any labels the client attached. Entries are linked by a keyed hash chain, so a change made to the record outside the service is detected at the CSN where it happened.

What you do with it#

Write state with declarations. You send TERSL declarations to a namespace and the service applies them as one unit, records one entry and answers with the new CSN. The declarations are the same ones the language section describes in Writing with declarations. A write that is refused, for a grant, an invalid line or a stale expected CSN, changes nothing.

Read with queries. The same request can carry TERSL queries after the declarations, and the answer comes back in the same response. Queries are described in Reading with queries. A key sees only the parts of the namespace its grants make visible; anything else is absent from the answer.

Inspect history. A key that holds the history right can page through the record, entry by entry, and check the hash chain on what it receives. The portal's History page shows the same record and adds a finder and a diff.

Read the namespace as it was at a moment. Any query can be run against the state at an earlier CSN or time, either with a request header or with an address of the form 7QK4M2C@4096. The portal's As of page does the same in a browser.

Copy a namespace from a moment. An administrator can create a new namespace that starts as an exact copy of another at a chosen CSN or time, with the source's grants. The copy is read-only until its administrator lifts the flag, and it keeps its own history from then on. Use it to recover from a bad write without changing the original record, or to branch a namespace for an experiment.

Administer it in the portal. The TERSL/DB portal is the web application where you create and delete namespaces, issue and revoke keys, edit grants, add users, browse state and history, export and load whole files, read the account's event log, and manage the plan. The portal guide has a page for each.

TERSL/DB and the open-source language#

TERSL/DB stores and serves the same language that the open-source specification and implementations in terse-lang/terse define. A namespace exports as one .terse file, and the open-source tools read that file as they read any other. A .terse file produced by those tools can be loaded into a namespace. What TERSL/DB adds is what a single file cannot provide on its own: many writers at once with a defined order, per-key access, a verifiable record of every change, reads at earlier moments, copies, and plan limits.

Where to go next#