Gc.Ttlseconds

Gc.ttlseconds is CockroachDB’s retention setting for overwritten values before garbage collection removes them. It defines how far back time travel queries can reach and therefore limits how much historical state SpiceDB can access. Shorter values reduce retained history, while longer values expand the usable snapshot window.

What the retention setting actually controls

Gc.ttlseconds is not a generic database cleanup knob, it defines how long overwritten row versions remain eligible for historical reads before garbage collection removes them. That makes it the practical boundary for how far back time travel queries can reach and how much past state a system like SpiceDB can still inspect.

The key operational trade-off is simple: longer retention preserves a wider snapshot window and supports more historical lookups, while shorter retention reclaims storage sooner and reduces the amount of stale data left in the cluster.

Why the snapshot window matters

Because the setting governs retained history, it influences whether a query can resolve against an earlier point in time or only the current state. For systems that depend on time-aware access decisions, audit-style inspection, or delayed consistency handling, that window can be the difference between a successful historical read and an unavailable one.

This is especially important when downstream logic expects the database to preserve enough history to compare past and present values. If the retention window is too short for the workload, older revisions disappear before they can be queried, even though the application still expects them to exist.

For broader database and storage governance, the same retention choice also affects space usage and compaction pressure. More retained history means more data carried forward until garbage collection can safely remove it.

How it behaves in practice

In practice, Gc.ttlseconds is best understood as a time-bound data-retention policy for overwritten values, not for active rows alone. Once a value is replaced, the old version stays around for the configured interval so reads can still reconstruct an earlier state.

The setting therefore interacts with both application semantics and operational housekeeping. If the value is tuned aggressively low, historical reads become fragile. If it is tuned high without a corresponding need, storage overhead grows and obsolete versions persist longer than necessary.

That makes the setting a good fit for environments where query correctness depends on bounded history, but not for workloads that assume long-term archival. It controls transient version retention, not durable backup retention.

Choosing an appropriate retention period

The right value depends on the oldest point in time your application must query successfully. A retention period should comfortably exceed the maximum expected lag between write activity and any historical lookup that might need the prior version.

When the workload includes access control, audit, or replay-style reads, teams should verify the setting against real query patterns rather than guessing from storage capacity alone. A value that is operationally convenient can still be functionally too short.

Why practitioners should care: Retention settings are easy to treat as infrastructure housekeeping, but here they directly shape application correctness. If historical state matters to policy evaluation or investigation, the chosen TTL becomes part of the system’s functional contract.

Practitioner takeaway: Tune Gc.ttlseconds from the oldest legitimate historical-read requirement, then confirm the resulting storage cost is still acceptable.