Skip to main content

Cluster licensing

Multi-node clustering requires an Enterprise license

Any [cluster] section in scramdb.toml, including a single-node cluster-of-one, is an Enterprise or Trial capability. A Community node started with [cluster] configured does not degrade to single-node: it refuses to start at all, logs exactly why, and exits. Single-node ScramDB, with no [cluster] section, is unrestricted and free on every edition.

By the end of this page you will know exactly how ScramDB supplies and checks a cluster license, what a node reports when that license is missing, invalid, or past its term, what the license actually governs, and how to confirm your own node's license is active.

The gate, and exactly when it fires​

A node reads its [cluster] section at startup. If that section is present, however minimal, one check runs before anything else: before this node resolves its own identity, and before it binds any port, including its cluster transport port. That check is simple: is the resolved license Enterprise or Trial? Community, including a Community node that was never given a key at all, fails it.

A node that fails this check does not fall back to single-node. It logs the reason and exits with a non-zero status:

cluster mode requires an Enterprise license (multi-node clustering is an
Enterprise-only capability); this node's license resolved to Community -
<reason>. Remove [cluster] from the config to run single-node, or configure
license_key / SCRAMDB_LICENSE_KEY with a valid Enterprise license to enable
clustering.

<reason> is filled in with exactly why the license resolved to Community; see What a node reports below for the three shapes it takes.

A node with no [cluster] section at all never runs this check. Single-node ScramDB has no license gate of any kind and is fully functional on every edition, including Community with no license key configured at all.

Supplying a license​

A license is a string token, not a file. There is no license-file path convention: ScramDB does not read a license.dat, a PEM file, or anything similar for this purpose. You supply the token itself through one of two places, checked in this order:

  1. The SCRAMDB_LICENSE_KEY environment variable. Takes precedence if both are set.
  2. license_key under [general] in scramdb.toml.
[general]
license_key = "your-enterprise-or-trial-key"

Every node in a cluster needs its own valid key configured; there is no cluster-wide "one node holds the license for everyone" shortcut. Treat the key like any other credential: keep it out of source control, and prefer the environment variable over committing it to a config file wherever your deployment tooling allows it.

What a node reports: missing, invalid, expired​

A node logs one line summarizing what its license resolved to on every startup, cluster or not. If what it resolved to is not what you configured, whether because a key you supplied did not verify, or because it verified but no longer authorizes the binary you're running, a second line names exactly why, at ERROR level, prefixed license DEGRADED:. An intentionally absent key is not treated as degraded: it is Community by design, and only logs at INFO.

No key configured at all (neither SCRAMDB_LICENSE_KEY nor [general] license_key set):

no license key configured (SCRAMDB_LICENSE_KEY unset, [general] license_key
unset): running Community edition

A key was supplied but failed to verify (malformed, tampered, an unrecognized or revoked signing key, or a schema newer than this build understands):

license key was supplied but failed to verify (<why>); running Community edition

<why> is one of: license token is malformed, license token armor is invalid, license key_id is not a recognized trust anchor, license key_id has been denied, license signature is invalid, license payload could not be decrypted, or license schema_version is newer than this build supports.

A key verified, but does not authorize this build. ScramDB's term check is not a live clock: it compares your license's authorized-through date against the date this specific binary was built, decided once at startup and never rechecked while the process keeps running. A node that already started stays exactly as it resolved for its whole process lifetime; the check only matters again the next time you restart or upgrade to a binary built after your license's term ends.

license key_id=<id> (edition <edition>) authorizes binaries built through
<expires_at>; this binary was built <build_date>, which is after the term
ended, so this node runs as Community until the license is renewed

(Both timestamps are Unix seconds, exactly as logged.)

In every one of these three cases, the resolved edition is Community, and a [cluster] section on that node hits the gate above with the matching <reason> filled in.

What the license governs, and what it does not​

Clustering itself. The one thing actually enforced, and enforced hard: whether [cluster] is allowed to start at all. There is no partial or degraded clustering tier; it is Enterprise/Trial or nothing.

A node-count ceiling, reported but not enforced at join time. An Enterprise or Trial license carries its own node-count claim, and a running node exposes both that ceiling and the node count it currently sees (see Verifying a license is active below). ScramDB does not automatically refuse the Nth node past that ceiling when it tries to join today; treat the ceiling as what your license entitles you to run, not as a technical limit the engine polices for you.

A data ceiling, enforced continuously, independent of clustering. Community edition, and any node currently degraded to Community for one of the three reasons above, is capped at 64 GiB of stored data. A background check samples total data size roughly once a second; crossing the cap flips the node read-only for INSERT, UPDATE, DELETE, MERGE, TRUNCATE, and COPY FROM, with a SQLSTATE 25006 error naming the cap. Reads, SELECT, and COPY TO/export are never affected, and write access resumes automatically the moment data drops back under the cap, no restart required. This gate has nothing to do with clustering specifically: it applies to a Community single-node instance exactly as it applies to a Community-degraded cluster node. Enterprise and Trial editions have no data ceiling.

Community versus Enterprise, for clustering specifically​

Single-node ScramDB works fully, with no caveats beyond the data ceiling above, and is free on Community. The moment you want more than one node, even a cluster-of-one as a stepping stone (see Forming a cluster), you need an Enterprise or Trial license. There is no free or Community tier for clustering at any node count.

Verifying a license is active​

Two independent ways to check, and they agree with each other.

The startup log. Every node logs a license: line at INFO on every boot, naming its resolved edition, licensee, key id, node cap, and data cap. If a license DEGRADED: line follows it, something about the configured key was rejected or has expired; see What a node reports above for what each shape means.

The metrics endpoint, live for the life of the process, not just at startup:

curl -s http://127.0.0.1:9090/metrics | grep '^scramdb_license_'

Expect a block like:

scramdb_license_valid 1
scramdb_license_edition{edition="Enterprise"} 1
scramdb_license_node_count 3
scramdb_license_max_nodes 10
scramdb_license_read_only_active 0
scramdb_license_days_of_term_remaining 214

scramdb_license_valid is the one to alert on: 1 means the resolved license is exactly what you configured; 0 means it degraded, whether from a rejected key or an expired term. scramdb_license_days_of_term_remaining and the data-cap pair (scramdb_license_data_bytes / scramdb_license_data_cap) only appear once there is a real value to report, so their absence on a fresh Community node with no key is expected, not a bug. Port 9090 is the default metrics_port; adjust the URL if you've changed it.

If it fails: no scramdb_license_* lines at all usually means you scraped the wrong port, or metrics_port is set to 0 (disabled) in that node's config.

Getting a license​

Email info@scramdb.com to obtain an Enterprise or Trial license key.

Next​