Skip to content

Backup and Storage Governance

Oxydian edited this page Nov 12, 2026 · 1 revision

💾 Backup & Storage Governance — Atlas Logistics

This runbook describes operational procedures for managing database snapshots, preventing disk leaks, and auditing document storage.


1. Native SQLite ACID Backups (VACUUM INTO)

Background & Problem

Traditional file copying (cp / copy) while an SQLite database is operating in WAL mode can capture uncommitted WAL state or torn pages, resulting in corrupt backups.

Solution

Atlas Logistics executes native SQLite VACUUM INTO, which instructs the SQLite engine to flush pending pages and write a clean, defragmented, transactionally consistent snapshot to disk:

node src/scripts/backup-db.js

Script Execution Flow

  1. Detects active database (data/dev.db in development, or data/prod.db in production).
  2. Generates ISO-timestamped target path (e.g. backups/atlas-erp-v2-2026-11-12T11-18-32-214Z.db).
  3. Executes client.execute("VACUUM INTO '<safe_path>'").
  4. Logs execution metrics and verifies output file existence.

2. Document Pointer Governance & Garbage Collection

Policy

  • SQLite never stores binary BLOBs or absolute machine paths (C:\...).
  • SQLite stores relative path pointers (/api/documents/download/...) and cryptographic SHA-256 hashes.
  • Fastify resolves absolute storage locations at runtime using the DOCS_ROOT environment variable.

Automated Garbage Collector

When document records in SQLite are marked deleted or discarded, physical files on disk may become orphaned. The Garbage Collector reconciles SQLite with the disk:

# Dry-run mode: scans disk and lists orphaned files and reclaimable bytes
pnpm run clean:documents

# Active purge mode: permanently deletes orphaned files from storage
npx tsx src/scripts/documents-garbage-collector.ts --purge

Clone this wiki locally