CouchDB: the databases Saphan Studio creates
Which databases the set-up creates on your CouchDB node, the access rule each one gets, which of them are the only copy of what they hold, and the setting that cannot be changed later.
Saphan Studio keeps law and evidence in CouchDB. You supply the node — or let the setup page start one on this machine — and Saphan Studio creates its databases on it: the setup page does it when you press Set up Saphan Studio, and from a terminal the same work is one command:
It reads the node's address from your configuration and the administrator's credential from the credentials file, never from the command line. A database that already exists is left alone and reported; nothing is dropped and no container is started. Running it again is safe.
The system databases
The CouchDB image does not create them, and until they exist authentication and the change
feed behave in ways that are easy to misread as bugs. saphan infra databases creates all three:
_users, _replicator and _global_changes.
One database per class of thing Saphan Studio stores
The four classes differ in how they change and in whether they can be rebuilt, and that is what decides your backup duty:
| class | default name | created | changes by | rebuildable? |
|---|---|---|---|---|
| law | saphan_law | always | a ratification act | yes — it can be dropped and rebuilt from the repository |
| working material | saphan_work | always | supersession | no — the database is the only copy |
| record | none | only when its name is configured, or with --record-reader (saphan_record) | append only | no — the database is the only copy |
| telemetry | none | only when its name is configured | append only | no — the database is the only copy |
The names are configuration keys — class.law_db_name, class.work_db_name,
class.record_db_name and class.telemetry_db_name — and are yours to change before the first
run.
⚠ Every class but law is the only copy of what it holds. Whatever backup you run, it has to cover those databases. This site has no backup and restore procedure yet.
--record-reader also write-protects the record database and creates a read-only account for it,
so a start check can prove that only Saphan Studio can write there; the generated password goes
only to the credentials file. The setup page always passes it.
The access rule each database gets
Each database gets a _security document naming the one role that may administer it:
| database | role | shape |
|---|---|---|
| law | ratification | single writer, everyone else reads |
| working material, record | engine | engine-written |
| telemetry | capture | capture-only |
⚠ The roles must match the credentials that actually authenticate. A role named here that nothing authenticates as is a database nothing but the administrator can write to.
The setting you cannot change afterwards
CouchDB's shard and replica counts — q and n — are fixed when a database is created and
cannot be changed later. The default is q = 2, n = 1, sized for one node; on a cluster, pass
--q and --n the first time. Changing your mind means creating new databases and copying the
data across.
When it is done
Verifying an install is how you check what you have.
First run: setting the machine up at /setup
A machine with no owner is set up in a browser at /setup, or from a terminal with saphan install: the window, the screens, and the key that is shown once.
Air-gapped installation (Enterprise)
A package, installed system-wide on a host with no network path to anything — what it puts on the machine, and what still needs your hand afterwards.