SyndrDB | Backup & Restore

SyndrDB provides comprehensive backup and restore capabilities for database disaster recovery, migration, and environment cloning. Backups are created as compressed archives containing all bundles, indexes, documents, and metadata.

BACKUP DATABASE
RESTORE DATABASE

BACKUP DATABASE

Creates a compressed backup archive of a database including all bundles, indexes, documents, and metadata.

Syntax

BACKUP DATABASE "database_name" TO "backup_path" [WITH options]

Components

Component	Description	Required
database_name	Name of the database to backup	Yes
backup_path	Path where backup file will be saved	Yes
WITH options	Optional backup configuration	No

Backup Path

The backup path can be:

Relative: Saved to configured backup directory (default: ./backups)
Absolute: Saved to exact path specified
Extension: Automatically adds .sdb extension if not provided

Backup Options

Options are specified in the WITH clause:

Option	Values	Default	Description
COMPRESSION	`'gzip'`, `'zstd'`, `'none'`	`'gzip'`	Compression algorithm
INCLUDE_INDEXES	`true`, `false`	`true`	Include index files in backup

COMPRESSION

Controls the compression algorithm used for the backup archive:

gzip: Standard compression, good compatibility
zstd: Modern compression, better ratio and speed
none: No compression (fastest, largest files)

INCLUDE_INDEXES

Controls whether index files are included in the backup:

true: Backup includes all index files (faster restore)
false: Indexes excluded (smaller backup, slower restore)

Examples

Basic Backup

-- Simple backup with defaults (gzip compression, includes indexes)
BACKUP DATABASE "MyApp" TO "myapp_backup.sdb"
-- Saves to: ./backups/myapp_backup.sdb

Absolute Path Backup

-- Backup to specific location
BACKUP DATABASE "analytics" TO "/backups/production/analytics_2024_01_15.sdb"

Custom Compression

-- Use zstd compression for better ratio
BACKUP DATABASE "BigData" TO "bigdata_backup.sdb"
WITH COMPRESSION = 'zstd'

-- No compression for fastest backup
BACKUP DATABASE "SmallDB" TO "small_backup.sdb"
WITH COMPRESSION = 'none'

Exclude Indexes

-- Smaller backup without indexes (will rebuild on restore)
BACKUP DATABASE "TempData" TO "temp_backup.sdb"
WITH INCLUDE_INDEXES = false

Multiple Options

-- Combine multiple options
BACKUP DATABASE "Production" TO "prod_backup.sdb"
WITH COMPRESSION = 'zstd', INCLUDE_INDEXES = true

Backup Process

The backup operation performs these steps:

Validation: Checks if database exists
Checkpoint: Executes checkpoint to ensure data consistency
File Collection: Gathers all database files (bundles, indexes, documents)
Checksum Calculation: Computes CRC checksums for integrity validation
Metadata Copy: Copies Primary database metadata (Databases, Bundles)
Archive Creation: Creates compressed tar archive (.sdb file)
Validation: Verifies backup integrity after creation

Backup Contents

Each backup archive contains:

Bundle Files: All .bnd bundle definition files
Document Files: All document data files
Index Files: Hash and B-Tree index files (if INCLUDE_INDEXES = true)
Metadata: Primary database Databases and Bundles documents
Manifest: manifest.json with metadata and file checksums

Permissions

Required Permission: Admin
Only users with Admin permissions can create backups
TODO: This will be enforced when user authentication is implemented

Error Cases

Error	Cause	Solution
`database not found`	Database doesn't exist	Use `SHOW DATABASES` to verify database name
`invalid backup path`	Path is invalid or inaccessible	Check path permissions and directory existence
`invalid compression type`	Unknown compression value	Use 'gzip', 'zstd', or 'none'
`backup failed`	File system error or insufficient space	Check disk space and permissions

Best Practices

DO:

Include timestamps in backup filenames (e.g., db_2024_01_15.sdb)
Use zstd compression for production backups (best ratio)
Keep backups in a separate location from data files
Test restore procedures regularly
Include indexes for production databases

DON'T:

Don't backup to the same disk as the database
Don't use none compression for large databases
Don't forget to verify backups periodically
Don't rely on a single backup - maintain rotation

Complete Example

-- Daily backup with timestamp
BACKUP DATABASE "production" TO "prod_2024_01_15.sdb"
WITH COMPRESSION = 'zstd', INCLUDE_INDEXES = true
-- Response: Database 'production' backed up successfully to './backups/prod_2024_01_15.sdb' in 2.5s

-- Quick backup without indexes (smaller size)
BACKUP DATABASE "development" TO "dev_quick.sdb"
WITH COMPRESSION = 'gzip', INCLUDE_INDEXES = false

-- Full backup with absolute path
BACKUP DATABASE "analytics" TO "/mnt/backups/analytics_full.sdb"
WITH COMPRESSION = 'zstd', INCLUDE_INDEXES = true

RESTORE DATABASE

Restores a database from a backup archive created by the BACKUP DATABASE command.

Syntax

RESTORE DATABASE FROM "backup_path" AS "database_name" [WITH options]

Components

Component	Description	Required
backup_path	Path to the backup file (.sdb)	Yes
database_name	Name for the restored database	Yes
WITH options	Optional restore configuration	No

Restore Options

Options are specified in the WITH clause:

Option	Values	Default	Description
FORCE	`true`, `false`	`false`	Overwrite existing database

FORCE

Controls whether to overwrite an existing database:

false: Restore fails if database already exists (safe default)
true: Overwrites existing database with backup (destructive)

Examples

Basic Restore

-- Restore backup to new database
RESTORE DATABASE FROM "myapp_backup.sdb" AS "MyApp"

Restore with Absolute Path

-- Restore from specific location
RESTORE DATABASE FROM "/backups/production/analytics_2024_01_15.sdb" AS "analytics"

Force Overwrite

-- Overwrite existing database (DANGEROUS!)
RESTORE DATABASE FROM "prod_backup.sdb" AS "production"
WITH FORCE = true

Restore to Different Name

-- Restore production backup to test environment
RESTORE DATABASE FROM "prod_2024_01_15.sdb" AS "production-test"
-- Original database name in backup: "production"
-- Restored as: "production-test"

Restore Process

The restore operation performs these steps:

Validation: Checks if backup file exists and is readable
Extraction: Extracts backup archive to temporary directory
Checksum Verification: Verifies all file CRC checksums for integrity
Compatibility Check: Ensures backup is compatible with server version
Directory Creation: Creates database directory structure
File Copy: Copies all files from backup to database directory
Database Creation: Creates database in system (LOCKED state)
Metadata Restore: Restores Primary database metadata
Validation: Validates restored database structure
Rollback: If any step fails, entire operation is rolled back

Database Lock State

IMPORTANT: After restore, the database is in LOCKED state:

LOCKED databases are read-only
Prevents accidental writes to freshly restored data
Must manually unlock before making changes
Use UNLOCK DATABASE "name" to enable writes

Permissions

Required Permission: Admin
Only users with Admin permissions can restore databases
TODO: This will be enforced when user authentication is implemented

Error Cases

Error	Cause	Solution
`backup file not found`	Backup path doesn't exist	Verify backup file path
`database already exists`	Database name is in use	Use different name or `WITH FORCE = true`
`checksum verification failed`	Backup file is corrupted	Use different backup file
`incompatible backup version`	Backup from different server version	Check backup metadata
`restore failed`	File system error	Check disk space and permissions

Best Practices

DO:

Always verify backup file exists before restore
Use FORCE = false (default) to prevent accidental overwrites
Test restores in non-production environment first
Unlock database only after verifying restore success
Keep original database if possible (restore to different name)

DON'T:

Don't use FORCE = true without verifying you want to overwrite
Don't restore directly to production without testing
Don't forget to unlock database after restore
Don't assume restore will work - always test

Complete Example

-- Restore production backup to test environment
RESTORE DATABASE FROM "/backups/prod_2024_01_15.sdb" AS "production-test"
-- Response: Database 'production-test' restored successfully from '/backups/prod_2024_01_15.sdb' in 3.2s.
--           Database is LOCKED - use UNLOCK DATABASE to enable writes.

-- Verify the restore
USE "production-test";
SHOW BUNDLES;

-- If verification passes, unlock the database
UNLOCK DATABASE "production-test";

-- Now you can use the restored database
ADD DOCUMENT TO BUNDLE "Users" WITH VALUES (...);

Disaster Recovery Example

-- Production database is corrupted, restore from last known good backup
RESTORE DATABASE FROM "/backups/prod_2024_01_14.sdb" AS "production-recovery"

-- Verify the data
USE "production-recovery";
SELECT COUNT(*) FROM BUNDLE "Users";
SELECT COUNT(*) FROM BUNDLE "Orders";

-- If data looks good, can rename and use
-- (rename operations TBD in future SyndrDB version)

Last updated: March 2026

Table of Contents

BACKUP DATABASE

Syntax

Components

Backup Path

Backup Options

COMPRESSION

INCLUDE_INDEXES

Examples

Basic Backup

Absolute Path Backup

Custom Compression

Exclude Indexes

Multiple Options

Backup Process

Backup Contents

Permissions

Error Cases

Best Practices

Complete Example

RESTORE DATABASE

Syntax

Components

Restore Options

FORCE

Examples

Basic Restore

Restore with Absolute Path

Force Overwrite

Restore to Different Name

Restore Process

Database Lock State

Permissions

Error Cases

Best Practices

Complete Example

Disaster Recovery Example