The transactor
The transactor owns writes, logs, indexing, leases, and scheduled garbage collection. One process serves every database in its catalog.
Start a transactor
corium transactor --data-dir /srv/corium --listen 0.0.0.0:4334
The process prints the databases that it serves and the databases for which it
stands by. It exits with an error when it cannot acquire a lease and --ha is
not set.
Every flag below has an equivalent key in the configuration file. A flag on the command line always wins.
Identity and network
| Flag | Default | Effect |
|---|---|---|
--data-dir <path> | None. Required. | Data directory for the filesystem store and for logs. |
--listen <addr> | 127.0.0.1:4334 | gRPC listen address. |
--owner <id> | transactor-$HOSTNAME | Stable identity in lease records. Set it. |
--advertise <url> | None | Client endpoint that peers use to find the lease holder. |
--metrics-listen <addr> | None | Prometheus endpoint at /metrics. |
Set --owner to a stable value per member, for example the host name. A
restarted member then re-acquires its own unexpired lease at once. A service
manager usually does not export HOSTNAME, so the default becomes
transactor-local on every member.
CAUTION: Keep the metrics listener on a private network. The endpoint has no bearer-token authentication.
Storage selection
--store picks the backend: mem, fs, postgres, turso, or s3. The
default is fs. Each backend has its own flags and its own Cargo feature.
--store-plugin <path> loads a storage driver at startup, and
--store <kind>:<json> then selects it. See
storage backends.
Lease and availability
| Flag | Default | Effect |
|---|---|---|
--ha | Off | Stand by when another transactor holds the lease, instead of failing at startup. |
--lease-ttl-ms <n> | 5000 | Failover detection bound. Renewals run at one third of this value. |
--lease-wait-ms <n> | 15000 | How long startup waits for a held lease before it gives up. Ignored with --ha, which waits without limit. |
--heartbeat-ms <n> | 10000 | Subscription heartbeat interval. |
A lower time-to-live gives faster takeover. It also costs more root-store traffic, and it tolerates shorter pauses on the active member. See high availability.
Index publication pacing
| Flag | Default | Effect |
|---|---|---|
--index-interval-ms <n> | 5000 | Base interval between publications. |
--index-backoff <n> | 4 | Minimum wait before the next publication, as a multiple of the duration of the last one. 0 disables it. |
--index-tail-threshold <n> | 0 | Defer publication while fewer than this many datoms are pending. 0 publishes any pending work. |
--index-tail-deadline-ms <n> | 60000 | Longest that a small tail defers publication. |
These four values can also be changed per database at runtime. See index publication.
Garbage collection
| Flag | Default | Effect |
|---|---|---|
--gc-interval <duration> | 1h | Interval of the scheduled sweep. off disables it. |
--gc-window <duration> | 72h | Retain unreachable blobs for at least this long. |
Collection is serialized with index publication. See garbage collection.
Database functions
| Flag | Default | Effect |
|---|---|---|
--db-fn-fuel <n> | 1000000 | Execution credits per :db/fn call. |
--db-fn-memory-bytes <n> | 16777216 | Managed memory per :db/fn call. |
User :db/fn code runs on the transactor in a restricted Clojure interpreter.
The interpreter has no input or output access. These two budgets bound a
runaway function. Both flags need the cljrs feature, which is on by default.
Authentication, authorization, and TLS
| Flag | Effect |
|---|---|
--serve-token <secret> | Require this exact bearer token. Strict mode. |
--require-auth | Require the shared development token. Reject anonymous callers. |
--serve-open | Accept every request as anonymous. |
--oidc-issuer <url> | Accept tokens signed by this issuer. Strict mode. |
--authz-db <name> | Authorize every request against this policy database. |
--tls-cert <pem>, --tls-key <pem> | Serve TLS. Both are required together. |
The default is permissive. The server recognizes the shared development token,
and it also admits anonymous callers. Any of --serve-token, --require-auth,
or --oidc-issuer switches the server to strict mode.
Read authentication and TLS before you expose a transactor outside a private network.
Encryption keys
--storage-key <uri> names a key that this process can resolve. The flag is
repeatable, because one transactor hosts databases under different keys.
The same keyring holds key-encryption keys and protection class keys. A transactor needs no class key: it commits sealed values without opening them.
The process resolves every named key at startup. A misconfigured process therefore fails at startup and names the key. See encryption at rest.
Logging
Tracing is human-readable by default. --log-format json writes structured
logs. RUST_LOG filters them.
RUST_LOG=corium_transactor=debug,corium_peer=info \
corium --log-format json transactor --data-dir /srv/corium
--log-format is a global flag. It comes before the subcommand.
A production example
corium transactor \
--config /etc/corium/transactor.edn \
--listen 0.0.0.0:4334 \
--advertise http://txor-a.internal:4334 \
--owner txor-a \
--ha \
--metrics-listen 127.0.0.1:9464 \
--serve-token "$CORIUM_SERVE_TOKEN" \
--authz-db corium_authz \
--tls-cert /etc/corium/tls/server.pem \
--tls-key /etc/corium/tls/server.key
The configuration file holds the storage selection and the read-only discovery credentials. The command line holds the identity of the member.