atlas/docs/DATABASE.md

Database Persistence

Overview

AtlasOS now supports SQLite-based database persistence for configuration and state management. The database layer is optional - if no database path is provided, the system operates in in-memory mode (data is lost on restart).

Configuration

Set the ATLAS_DB_PATH environment variable to enable database persistence:

export ATLAS_DB_PATH=/var/lib/atlas/atlas.db
./atlas-api

If not set, the system defaults to data/atlas.db in the current directory.

Database Schema

The database includes tables for:

• users - User accounts and authentication
• audit_logs - Audit trail with indexes for efficient querying
• smb_shares - SMB/CIFS share configurations
• nfs_exports - NFS export configurations
• iscsi_targets - iSCSI target configurations
• iscsi_luns - iSCSI LUN mappings
• snapshot_policies - Automated snapshot policies

Current Status

✅ Database Infrastructure: Complete

• SQLite database connection and migration system
• Schema definitions for all entities
• Optional database mode (falls back to in-memory if not configured)

⏳ Store Migration: In Progress

• Stores currently use in-memory implementations
• Database-backed implementations can be added incrementally
• Pattern established for migration

Migration Pattern

To migrate a store to use the database:

1. Add database field to store struct
2. Update New*Store() to accept *db.DB parameter
3. Implement database queries in CRUD methods
4. Update app.go to pass database to store constructor

Example pattern:

type UserStore struct {
    db   *db.DB
    mu   sync.RWMutex
    // ... other fields
}

func NewUserStore(db *db.DB, auth *Service) *UserStore {
    // Initialize with database
}

func (s *UserStore) Create(...) (*User, error) {
    // Use database instead of in-memory map
    _, err := s.db.Exec("INSERT INTO users ...")
    // ...
}

Benefits

• Persistence: Configuration survives restarts
• Audit Trail: Historical audit logs preserved
• Scalability: Can migrate to PostgreSQL/MySQL later
• Backup: Simple file-based backup (SQLite database file)

Next Steps

1. Migrate user store to database (highest priority for security)
2. Migrate audit log store (for historical tracking)
3. Migrate storage service stores (SMB/NFS/iSCSI)
4. Migrate snapshot policy store
5. Add database backup/restore utilities