Time-Travel Queries

Executive Summary

The feature supports three query modes (AS OF TIMESTAMP, AS OF TRANSACTION, AS OF SCN) with automatic snapshot management, configurable retention policies (default 30 days), and O(1) snapshot lookup performance.

---

Problem Being Solved

Core Problem Statement

Organizations in regulated industries must prove data state at specific points in time for audits, compliance investigations, and incident analysis, but traditional embedded databases provide no mechanism to query historical data states without complex manual versioning schemes. Current workarounds involve full database backups, application-level change tracking, or expensive cloud database dependencies that violate edge computing requirements.

Who Suffers Most

• Compliance Officers: Must manually reconstruct data states from backups and logs during regulatory audits, risking penalties for incomplete records or extended investigation timelines.

• DevOps Engineers: Spend hours diagnosing production incidents by correlating logs with database backups, unable to query exact state at incident timestamp without full restore operations.

• Financial Auditors: Cannot efficiently validate account balances, transaction histories, or pricing data as it existed on specific dates without complex ETL processes from backup files.

---

Concrete Examples with Code, Config & Architecture

Example 1: Financial Audit Compliance - Embedded Configuration

Scenario: A fintech company must prove account balances and transaction history as they existed on December 31, 2024 for year-end regulatory audit. They deploy HeliosDB Lite embedded in their core banking microservice (Java/Rust) running on Kubernetes. Historical data must be retained for 90 days to satisfy regulatory requirements.

Architecture:

Banking Microservice (Java/Rust)
    ↓
 HeliosDB-Lite Client Library (JNI/FFI)
    ↓
In-Process Storage Engine (RocksDB)
    ├── Current Data (fast path): data:accounts:*
    ├── Versioned Data: v:accounts:*:{timestamp}
    └── Snapshot Metadata: snapshot:{timestamp}
    ↓
Persistent Volume (K8s PVC) - 2GB SSD

Configuration (heliosdb.toml):

# HeliosDB-Lite configuration for financial compliance
[database]
path = "/data/banking.db"
memory_limit_mb = 256
enable_wal = true
page_size = 4096

[storage]
# Enable time-travel for audit compliance
time_travel_enabled = true

[snapshot]
# Regulatory retention: 90 days
min_retention_seconds = 7776000  # 90 days
max_snapshots = 10000
auto_gc_enabled = true

[monitoring]
metrics_enabled = true
verbose_logging = false

---

Example 2: Healthcare HIPAA Compliance - Language Binding Integration (Python)

Scenario: A healthcare SaaS provider must track patient record access and modifications for HIPAA compliance audits. Their Python-based medical records system must prove who accessed what data at what time for the past 7 years. Using HeliosDB Lite's Python bindings, they implement audit-ready time-travel queries embedded in their Flask application running on-premise (air-gapped for patient privacy).

---

Example 3: E-Commerce Price History - Infrastructure & Container Deployment

Scenario: An e-commerce platform must track product price changes for competitive analysis, customer dispute resolution, and pricing algorithm validation. They deploy HeliosDB Lite in Docker containers on AWS ECS, running 10 microservice instances handling 1M products with 100M price change events. Historical price queries power customer support ("What was the price when I added to cart?") and analytics dashboards. 24-hour price retention for customer disputes, 90-day retention for analytics.

Docker Deployment (Dockerfile):

FROM rust:1.75-slim as builder

WORKDIR /app

# Copy source
COPY Cargo.toml Cargo.lock ./
COPY src ./src

# Build HeliosDB-Lite application with release optimizations
RUN cargo build --release --bin ecommerce-pricing-service

# Runtime stage (minimal image)
FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    ca-certificates \
    curl \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/ecommerce-pricing-service /usr/local/bin/

# Create data volume mount point
RUN mkdir -p /data

# Expose HTTP API port
EXPOSE 8080

# Health check endpoint
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# Set data directory as volume
VOLUME ["/data"]

ENTRYPOINT ["ecommerce-pricing-service"]
CMD ["--config", "/etc/heliosdb/config.toml", "--data-dir", "/data"]

Docker Compose (docker-compose.yml):

version: '3.8'

services:
  pricing-service:
    build:
      context: .
      dockerfile: Dockerfile
    image: ecommerce-pricing-service:latest
    container_name: pricing-service-prod

    ports:
      - "8080:8080"      # HTTP API

    volumes:
      - ./data:/data                                       # Persistent database
      - ./config/heliosdb.toml:/etc/heliosdb/config.toml:ro

    environment:
      RUST_LOG: "info,pricing_service=debug"
      HELIOSDB_DATA_DIR: "/data"
      SERVICE_NAME: "pricing-service"

    restart: unless-stopped

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 40s

    networks:
      - ecommerce-network

    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

networks:
  ecommerce-network:
    driver: bridge

volumes:
  pricing_data:
    driver: local

Kubernetes Deployment (k8s-deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pricing-service
  namespace: ecommerce
  labels:
    app: pricing-service
    tier: backend
spec:
  replicas: 10  # 10 microservice instances
  selector:
    matchLabels:
      app: pricing-service
  template:
    metadata:
      labels:
        app: pricing-service
    spec:
      containers:
      - name: pricing-service
        image: ecommerce-pricing-service:v2.5.0
        imagePullPolicy: Always

        ports:
        - containerPort: 8080
          name: http
          protocol: TCP

        env:
        - name: RUST_LOG
          value: "info"
        - name: HELIOSDB_DATA_DIR
          value: "/data"
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name

        volumeMounts:
        - name: data
          mountPath: /data
        - name: config
          mountPath: /etc/heliosdb
          readOnly: true

        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "1000m"

        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 3

        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
          timeoutSeconds: 3

      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: pricing-service-pvc
      - name: config
        configMap:
          name: heliosdb-config

---
apiVersion: v1
kind: Service
metadata:
  name: pricing-service
  namespace: ecommerce
spec:
  type: LoadBalancer
  selector:
    app: pricing-service
  ports:
  - port: 80
    targetPort: 8080
    name: http

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pricing-service-pvc
  namespace: ecommerce
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi
  storageClassName: gp3  # AWS EBS gp3 for cost/performance balance

Configuration for Container (config.toml):

[server]
host = "0.0.0.0"
port = 8080

[database]
path = "/data/pricing.db"
memory_limit_mb = 768
enable_wal = true
page_size = 4096

[storage]
# Enable time-travel for price history queries
time_travel_enabled = true

[snapshot]
# Analytics: 90 days (separate GC policy)
min_retention_seconds = 7776000  # 90 days
max_snapshots = 50000
auto_gc_enabled = true

[container]
enable_shutdown_on_signal = true
graceful_shutdown_timeout_secs = 30

API Usage Examples:

# Get current price
curl http://pricing-service/products/12345/price

# Get historical price (customer dispute: "What was price when I added to cart?")
curl "http://pricing-service/products/12345/price/history?timestamp=2025-11-25%2014:30:00"

# Update price (creates new version automatically)
curl -X POST http://pricing-service/products/price \
  -H "Content-Type: application/json" \
  -d '{"product_id": 12345, "new_price": 29.99}'

---

Example 4: SaaS Subscription Billing - Microservices Integration (Rust)

Scenario: A SaaS company provides usage-based billing for API consumption. They need to reconstruct customer usage and charges as they existed on invoice generation date for billing disputes ("I was charged wrong amount"). Deployed as Rust microservice on AWS Lambda + EFS for persistence.

Service Architecture:

┌──────────────────────────────────────────────────┐
│     HTTP Request (Customer Portal / API)          │
├──────────────────────────────────────────────────┤
│  Axum Service Handler (Async Tokio Runtime)       │
├──────────────────────────────────────────────────┤
│  HeliosDB-Lite Connection (Shared Arc)            │
│  ├── Record usage (versioned automatically)       │
│  ├── Generate invoice (AS OF TIMESTAMP lock)      │
│  └── Dispute investigation (time-travel query)    │
├──────────────────────────────────────────────────┤
│  In-Process Storage Engine (MVCC Time-Travel)     │
│  ├── usage_events: Current + 12-month history     │
│  └── invoices: Generated with snapshot references │
└──────────────────────────────────────────────────┘

API Usage:

# Record usage (happens throughout the month)
curl -X POST http://billing-service/usage \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cust_123", "api_calls": 5000, "storage_gb": 10.5, "bandwidth_gb": 2.3}'

# Generate invoice (locks data to current snapshot)
curl -X POST http://billing-service/invoices/cust_123/generate

# Dispute investigation (reconstruct exact invoice data)
curl http://billing-service/invoices/98765/dispute

---

Example 5: Industrial IoT Edge Sync - Edge Computing & Offline-First

Edge Device Configuration:

[database]
# Minimal resource footprint for Raspberry Pi
path = "/var/lib/heliosdb/factory_sensors.db"
memory_limit_mb = 96         # Ultra-low memory for IoT
page_size = 512              # Smaller pages for SD card
enable_wal = true
cache_mb = 32

[storage]
# Enable time-travel for incident investigation
time_travel_enabled = true

[snapshot]
# Local retention: 7 days (long enough for incident investigation)
min_retention_seconds = 604800  # 7 days
max_snapshots = 10000
auto_gc_enabled = true

[sync]
# Optional cloud sync for collected data (when connectivity available)
enable_remote_sync = true
sync_interval_secs = 3600      # Hourly sync attempts
sync_endpoint = "https://factory-cloud.example.com/sync"
batch_size = 5000
retry_on_failure = true
max_retry_attempts = 10

[logging]
# Minimal logging for edge devices
level = "warn"
output = "syslog"

Key Benefits:

• Offline-first: Operates independently of network connectivity
• Incident investigation: Query exact sensor state at failure timestamp

---

Adoption Strategy

Phase 1: Proof of Concept (Weeks 1-4)

Target: Validate time-travel queries in target environment (single table/microservice)

Tactics:

• Deploy HeliosDB Lite to single microservice or edge device
• Enable time-travel on critical audit table (e.g., transactions, patient_records, usage_events)
• Configure retention policy matching regulatory requirements
• Run parallel queries (current + time-travel) to validate results
• Collect baseline performance metrics (latency, memory, storage)

Example PoC Scope (Financial Services):

-- Enable on transactions table
CREATE TABLE transactions (
    txn_id INTEGER PRIMARY KEY,
    account_id INTEGER NOT NULL,
    amount DECIMAL(15,2) NOT NULL,
    timestamp INTEGER DEFAULT (strftime('%s', 'now'))
);

-- PoC Test: Query balance as of year-end
SELECT SUM(amount)
FROM transactions
AS OF TIMESTAMP '2024-12-31 23:59:59'
WHERE account_id = 1001;

Phase 2: Pilot Deployment (Weeks 5-12)

Tactics:

• Expand to 3-5 critical tables requiring audit trails
• Integrate time-travel queries into compliance workflows (e.g., audit dashboards)
• Monitor performance and stability under production load
• Gather feedback from compliance officers, DevOps, and auditors

Example Pilot Use Cases:

• Financial audit: Year-end balance reconciliation
• Incident investigation: Query state before/after production incidents
• Billing disputes: Reconstruct invoice data as it existed at generation time
• Compliance queries: HIPAA/GDPR access log analysis
• Analytics: Historical trend analysis (price changes, usage patterns)

Phase 3: Full Rollout

Tactics:

• Automate deployment via CI/CD pipeline (Docker/K8s rollout)
• Implement centralized monitoring for snapshot health (Prometheus/Grafana)
• Train teams on time-travel query syntax and best practices
• Establish retention policy standards by use case (24 hours, 30 days, 7 years)
• Create runbooks for incident investigation and compliance queries

Organizational Rollout Order:

• Weeks 13-14: Financial systems (transactions, accounts, balances)
• Weeks 15-16: Compliance systems (access logs, audit trails, change logs)
• Weeks 17-18: Customer-facing systems (billing, support tickets, user actions)
• Weeks 19-20: Edge devices (IoT sensors, edge gateways, field equipment)

---

Conclusion

Call to Action: If your organization faces regulatory audit requirements, customer dispute resolution challenges, or incident investigation bottlenecks—and cannot accept cloud database dependencies or manual versioning complexity—HeliosDB Lite's Time-Travel Queries provide immediate ROI through automated compliance, faster diagnosis, and zero infrastructure costs.