BoltDB Schema Management#

Overview#

Atlantis uses bbolt (an embedded key-value store) as its persistent data layer, stored as atlantis.db in the configured data directory 1. The BoltDB struct wraps the raw bolt database and provides three named buckets:

2

All values are JSON-serialized Go structs. There is no formal schema versioning — backward compatibility is managed through startup migrations, tolerate-and-overwrite logic, and preserve-on-reset semantics.

Lock Key Schema (runLocks bucket)#

Key Format#

Lock keys were migrated from a 3-part to a 4-part format to support named projects:

• Old format: {repoFullName}/{path}/{workspace}
• New format: {repoFullName}/{path}/{workspace}/{projectName}

The canonical key producer is models.GenerateLockKey. Validity is checked by locking.IsCurrentLocking, which applies a regex requiring exactly four path segments.

Startup Migration#

At startup, New() runs a one-time migration inside a BoltDB write transaction:

1. Scans every key in runLocks.
2. For keys that fail locking.IsCurrentLocking (i.e., old 3-part format), deserializes the value and generates a new key via models.GenerateLockKey.
3. Writes the value under the new key and deletes the old key.

Failures are logged as warnings but do not abort startup 3. Old-format keys continue to work until the migration succeeds.

Pull Status Schema (pulls bucket)#

Key Format#

Pull status keys follow the pattern {hostname}::{repoFullName}::{pullNum}, validated to reject any component containing the :: separator 4.

Value Structure#

Each key stores a JSON-serialized models.PullStatus, containing:

• Pull — a models.PullRequest snapshot with HeadCommit and BaseBranch as freshness fields.
• Projects — a []models.ProjectStatus slice, each holding Status and PolicyStatus.

Write Logic and Freshness#

UpdatePullWithResults is the single write path. On every plan or apply result it:

1. Reads the current entry.
2. Calls pullStatusOutdatedForPull: returns true if HeadCommit differs, or if BaseBranch changed (same-head retargets require a new plan).
3. If outdated (reset): starts a fresh PullStatus from the new results but copies forward any PolicyStatus from matching old projects 5. This preserves policy approvals in the window between the plan DB write and the subsequent policy-check DB write.
4. If current (merge): updates only the projects present in newResults, leaving unrelated projects untouched 6.

Backward Compatibility: Tolerate-and-Overwrite#

If getPullFromBucket returns a deserialization error (e.g., after a schema change renders existing JSON unreadable), UpdatePullWithResults logs a warning and treats the entry as absent, overwriting it with fresh data 7. In-flight policy approvals in the old blob are lost, but the server does not crash or block.

Policy Approval Schema (PolicySetStatus)#

Evolution (PR #6271)#

PR #6271 "feat: sticky policy approvals" replaced a simple integer approval count with a structured, hash-based model:

The PolicySetApproval struct stores Approver string and Hashes []string (the policy item hashes at time of approval). PolicySetStatus.GetCurApprovals() counts only approvals whose recorded hashes still cover all current Hashes, filtering out stale approvals.

Approval Persistence Across Commits#

When a commit is pushed (reset path in UpdatePullWithResults), existing PolicyStatus is copied forward to the new PullStatus entry 5. The doPolicyCheck runner then applies sticky-approval carry-forward logic and overwrites these with validated results.

Backward Compatibility#

The same tolerate-and-overwrite mechanism described above handles old blobs serialized with integer Approvals fields. The schema breakage is logged; the PR was written with explicit acceptance that in-flight approvals are lost on first upgrade 8.

Key Source Files#