@douglance/stdb-backup

Filesystem-based backup and restore utilities for SpacetimeDB databases.

Installation

npm install -g @douglance/stdb-backup
# or
bun install -g @douglance/stdb-backup

Features

• Database Address Support: Use SpacetimeDB addresses (c200... hashes) directly!
• Instant Snapshots: Create compressed backups of SpacetimeDB databases
• Fast Restoration: Restore databases from snapshots in seconds
• Safety Checks: Warns if SpacetimeDB server is running during backup
• Database Discovery: Lists all databases with addresses and timestamps
• CLI Tool: Simple command-line interface
• Automatic Resolution: Accepts both addresses and replica IDs

Quick Start

List Databases

import { FilesystemSnapshot } from '@douglance/stdb-backup';

const snapshot = new FilesystemSnapshot();
const databases = await snapshot.list();

for (const db of databases) {
  console.log(db.address);   // c200080000000008002600240ab586b24ba4d627...
  console.log(db.identity);  // 150000007
  console.log(db.name);      // game-name (if available)
}

Create Snapshot

// Use database address (recommended - matches what you use in code!)
await snapshot.create({
  databaseIdentity: 'c200080000000008002600240ab586b24ba4d62794e9724d065e68f854d76daf',
  output: './backups/my-game.tar.gz',
  compress: true,
});

// Or use replica ID
await snapshot.create({
  databaseIdentity: '150000007',
  output: './backups/my-game.tar.gz',
  compress: true,
});

Restore Snapshot

await snapshot.restore({
  input: './backups/my-game.tar.gz',
  databaseIdentity: '150000009', // Replica ID or address works
  force: true,
});

CLI Usage

Step 1: Find your database

# List all local databases with addresses
stdb snapshot list

Output shows:

• Database addresses (the c200... hash you use in code)
• Replica IDs (numeric identifiers like 150000007)
• Last modified time
• File paths

Step 2: Create a snapshot

# Use database address (recommended)
stdb snapshot save <address-or-id> -o <output-file>

# Examples:
stdb snapshot save c200080000000008002600240ab586b24ba4d627... -o ./backup.tar.gz
stdb snapshot save 150000007 -o ./backup.tar.gz

Step 3: Restore from snapshot

# Restore to any replica ID
stdb snapshot restore <snapshot-file> <address-or-id> --force

Complete Example:

# 1. See what databases you have (shows addresses!)
stdb snapshot list

# 2. Create backup using database address (c200...)
stdb snapshot save c200080000000008002600240ab586b24ba4d62794e9724d065e68f854d76daf -o ./backup.tar.gz

# 3. Or use the numeric replica ID
stdb snapshot save 150000007 -o ./backup.tar.gz

# 4. Restore to a different database
stdb snapshot restore ./backup.tar.gz 150000009 --force

Using Database Addresses:

• You can now use the SpacetimeDB address (the c200... hash you know from your code!)
• Run stdb snapshot list to see addresses for all local databases
• Both addresses and numeric replica IDs work interchangeably
• The tool automatically resolves addresses to replica IDs

Safety

⚠️ IMPORTANT: For safe backups, stop SpacetimeDB before creating snapshots:

# Stop server
spacetime server stop

# Create snapshot
stdb snapshot save 150000007 -o ./backup.tar.gz

# Restart server
spacetime server start

API Reference

FilesystemSnapshot

list(): Promise<DatabaseInfo[]>

Lists all databases in the SpacetimeDB data directory.

Returns:

• identity: Replica ID (numeric identifier like 150000007)
• address: Database address (c200... hash) - use this to match your code!
• name: Database name (if available from control database)
• path: Absolute path to database directory
• modifiedAt: Last modification timestamp
• sizeBytes: Size in bytes (currently 0 for performance)

create(options): Promise<void>

Creates a compressed snapshot of a database.

Options:

• databaseIdentity: Database address (c200...) or replica ID (150000007)
• output: Path to output file (.tar.gz)
• compress: Enable gzip compression (default: true)

restore(options): Promise<void>

Restores a database from a snapshot.

Options:

• input: Path to snapshot file
• databaseIdentity: Target database address or replica ID
• force: Overwrite existing database (default: false)

Data Directory Structure

SpacetimeDB stores local databases at:

~/.local/share/spacetime/data/
├── control-db/
│   └── db                      ← Contains address mappings
├── replicas/
│   ├── 148000007/              ← Database directories (replica IDs)
│   ├── 150000001/
│   ├── 150000007/
│   └── ...
└── spacetime.pid

How It Works:

• Databases are stored in directories with numeric replica IDs (148000007, 150000001, etc.)
• Each database has a unique address (c200... hash) stored in the control database
• This tool extracts addresses from the control database for easy identification
• You can use either format (address or replica ID) when creating/restoring snapshots
• Addresses match what you use in your SpacetimeDB client code!

Examples

See examples/ directory for complete working examples.

Tested

✅ Successfully tested with 8 databases ✅ Database address extraction from control database verified ✅ Address-to-replica-ID resolution working ✅ Snapshot creation works (191 KB compressed from 5.04 MB database) ✅ Snapshot restoration verified ✅ Safety checks functional (detects running server) ✅ Both addresses and replica IDs work for all operations

License

MIT