The DittoDatabase resource is the fundamental building block of Edge Server deployments. Each database manages its own data namespace, synchronization settings, and peer connections, enabling distributed data sync across your mesh network.

​
Basic Configuration

Every Edge Server deployment requires at least one DittoDatabase resource: 
resources:
  my_database:
    resource_type: DittoDatabase
    db_id: "12345678-1234-4123-1234-123456789012"  # UUID format
    device_name: "edge-device-1"
    subscriptions:
      - "SELECT * FROM sensors WHERE location = 'warehouse'"
    auth:
      server:
        access_token: "YOUR_TOKEN"
        auth_url: "https://your-app.cloud.dittolive.app"
        provider: "__playgroundProvider"
See the DittoDatabase configuration reference for complete details.

​
Authentication Modes

Every database must specify how it authenticates with the mesh network. Choose between cloud-connected or offline modes:

​
Cloud/Server Authentication

Connect to Ditto Cloud or a self-hosted server for centralized auth and optional cloud sync: 
auth:
  server:
    access_token: "YOUR_TOKEN"
    auth_url: "https://your-app.cloud.dittolive.app"
    provider: "__playgroundProvider"  # Use custom provider in production
    enable_cloud_sync: true  # Optional, defaults to true

​
Offline Small Peer Mode

For completely offline deployments without cloud connectivity: 
auth:
  small_peer_only:
    offline_license_token: "YOUR_OFFLINE_LICENSE"
    key_b64: "optional_shared_key"  # Optional encryption key

​
Data Synchronization

Control what data syncs to this Edge Server using DQL subscriptions: 
resources:
  my_database:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    auth:
      # ... auth configuration
    subscriptions:
      # Simple query
      - "SELECT * FROM sensors WHERE location = 'warehouse'"
      
      # Parameterized query
      - query: "SELECT * FROM events WHERE priority >= :min_priority"
        args:
          min_priority: 3

​
Best Practices

  1. Use UUIDs for db_id: Always use valid UUIDv4 format for database IDs
  2. Descriptive device names: Choose meaningful names for easier debugging
  3. Limit subscriptions: Only sync data you need to minimize bandwidth and storage
  4. Secure credentials: Use environment variables or secrets management for tokens
  5. Plan persistence: Choose appropriate storage locations with sufficient space
  6. Test connectivity: Verify network paths before deploying to production

​
Troubleshooting

​
Database Won’t Start

Check:
  • db_id is valid UUIDv4 format
  • Authentication credentials are correct
  • Persistence directory has write permissions
  • No other process is using the same database files

​
Peers Not Syncing

Verify:
  • Both peers have the same db_id
  • Authentication modes are compatible
  • Network connectivity exists between peers
  • Firewall rules allow Ditto traffic

​
High Disk Usage

Review:
  • Subscription queries aren’t too broad
  • Log level isn’t set to verbose
  • Old log files are being rotated/cleaned