Application Snapshots & Checkpoints
NodeStack features Application Snapshots & Checkpoints via SnapshotService. A snapshot captures a self-contained, point-in-time state of an application—combining its embedded SQLite database, uploaded media assets, schema definitions, and cryptographic content hashes.
Snapshots provide time-travel recovery across development, demo presentations, integration testing, and production maintenance workflows.
Architectural Guarantees
Every snapshot created by NodeStack guarantees:
- Atomic Transactional Database Snapshot: Uses SQLite's native
VACUUM INTOcommand, capturing a consistent, uncorrupted database copy without downtime or table locks. - Media & File Asset Synchronization: Copies uploaded assets from
storage/alongside the database, ensuring uploaded images and documents match the exact record state. - Deterministic Schema & Content Hashing: Computes SHA-256 hashes of collection schemas and database content to dynamically detect state drift from the active snapshot.
- Non-Destructive Time-Travel: Restoring to an older snapshot preserves all subsequent checkpoints, allowing you to move forward and backward across different states at will.
- Multi-Tenant Isolation: In multi-application environments, snapshots are strictly scoped per application tenant (
/api/apps/:appId/snapshots).
Capacity Limit & FIFO Eviction Safeguard
To prevent unbounded disk usage, NodeStack enforces a hard limit of 10 snapshots per application:
- Attempting to create an 11th snapshot without confirmation rejects with HTTP 409 Conflict (
SNAPSHOT_LIMIT_REACHED). - Callers can pass
evictOldest: true(or--evict-oldestin CLI) to safely purge the oldest snapshot before saving the new checkpoint. - The Admin UI displays an interactive capacity warning with metadata of the snapshot to be replaced before prompting confirmation.
Web Admin Dashboard
The Snapshots view in the Admin UI (http://localhost:8090/_/):
- Displays active baseline status and live database drift indicators.
- Visualizes chronological checkpoint history with record counts, storage sizes, and creation timestamps.
- Provides 1-click non-destructive restoration with safety confirmation modals.
- Seamlessly switches histories when changing the active tenant in the Multi-App switcher.
Client SDK (nodestack-client)
The client.snapshots service provides complete programmatic control:
import NodeStackClient from 'nodestack-client';
const client = new NodeStackClient('http://localhost:8090');
// Authenticate as superuser / admin
await client.admins.authWithPassword('admin@example.com', 'AdminPassword123!');
// 1. Create a snapshot checkpoint
const snapshot = await client.snapshots.create({
label: 'Pre-Deployment Baseline',
description: 'Clean database state before running schema migrations',
evictOldest: true, // Auto-evict oldest if at 10-snapshot capacity
});
// 2. List all snapshots & monitor drift
const status = await client.snapshots.list();
console.log(`Retained snapshots: ${status.snapshots.length}/10`);
console.log(`Has data drifted: ${status.driftDetected}`);
// 3. Restore to checkpoint
await client.snapshots.restore(snapshot.id);
// 4. Delete an individual checkpoint
await client.snapshots.delete(snapshot.id);
Application-Scoped Snapshots
When managing a tenant application, use client.app(slug).snapshots:
const shopClient = client.app('shop');
const shopSnapshots = await shopClient.snapshots.list();
CLI Commands
You can manage checkpoints directly from your terminal:
# List all snapshots and drift status
npx @nodestackapp/server snapshots list
# Create a new snapshot checkpoint
npx @nodestackapp/server snapshots create --label "Pre-Update" --description "Catalog backup"
# Force oldest eviction if at the 10-snapshot limit
npx @nodestackapp/server snapshots create --label "Nightly" --evict-oldest
# Restore to a specific snapshot ID
npx @nodestackapp/server snapshots restore <snapshot-id>
# Delete a specific snapshot
npx @nodestackapp/server snapshots delete <snapshot-id>
# Clear all snapshots
npx @nodestackapp/server snapshots clear