The DittoDatabase resource is the fundamental building block of Edge Server deployments. It manages a single Ditto database instance that can synchronize data across devices using peer-to-peer protocols and optionally sync with Ditto Cloud or self-hosted servers.

​
Basic Configuration

resources:
  my_database:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"  # UUID format required
    device_name: "edge-device-1"
    auth:
      # Authentication configuration (see below)

​
Required Fields

FieldTypeDescription
resource_typestringMust be "DittoDatabase"
db_idstringUnique database identifier in UUIDv4 format (e.g., "12345678-1234-4123-1234-123456789012"). Must be unique across all DittoDatabase resources in the config
device_namestringEdge server device name on the mesh (minimum 1 character)
authobjectAuthentication configuration (see Authentication section below)

​
Authentication Methods

The auth field determines how the database connects to the mesh. You must choose one of two authentication methods:

​
Cloud/Server Authentication

Connect to Ditto Cloud or a self-hosted Ditto server for centralized authentication and optional cloud sync: 
auth:
  server:
    access_token: "YOUR_TOKEN"
    auth_url: "https://YOUR-AUTH-URL.cloud.dittolive.app"
    provider: "__playgroundProvider"  # or your custom webhook provider
    enable_cloud_sync: true  # Optional, defaults to true
FieldTypeRequiredDescription
access_tokenstringYesToken used to authenticate with the authentication provider
auth_urlstring (URL)YesAuthentication URL for cloud sync
providerstringYesWebhook provider configured in Ditto Portal. Use "__playgroundProvider" for development/playground mode
enable_cloud_syncbooleanNoEnable automatic cloud synchronization (default: true)

​
Small Peer Only Mode

For offline mesh networks without cloud connectivity: 
auth:
  small_peer_only:
    offline_license_token: "YOUR_OFFLINE_LICENSE_TOKEN"
    key_b64: "optional_base64_key"  # Optional
FieldTypeRequiredDescription
offline_license_tokenstringYesOffline license token for SmallPeerOnly mode
key_b64stringNoOptional base64-encoded key for shared key encryption

​
Optional Configuration

​
Subscriptions

Define DQL subscriptions to register with this database: 
subscriptions:
  # Simple string query
  - "SELECT * FROM cars"
  
  # Query with arguments
  - query: "SELECT * FROM cars WHERE color == :color"
    args:
      color: "blue"
Subscriptions can be:
  • Simple strings: Direct DQL queries without parameters
  • Objects with arguments: DQL queries with named parameters using the :param syntax

​
Persistence Directory

Control where the database stores its files: 
persistence_dir: from_current_exe  # Default
Options:
  • "from_current_exe" - Store in directory adjacent to Edge Server executable (default)
  • "temp_dir" - Use temporary directory (useful for testing)
  • { path: "path/to/dir" } - Specify a custom path (relative to config file or absolute)
  • { from_env: "ENV_VAR_NAME" } - Read path from environment variable

​
Transport Configuration

Fine-tune how the database communicates with other peers: 
transport_config:
  peer_to_peer:
    ble_enabled: true
    lan_enabled: true
    lan_mdns_enabled: true  # Auto-discover peers with same db_id
    lan_multicast_enabled: false
  
  connect_config:
    known_tcp_servers: ["192.168.1.100:4040"]
    known_ws_servers: ["ws://example.com:8080"]
    retry_interval_msec: 5000
  
  listen_config:
    tcp_listen:
      enable: true
      ip: "0.0.0.0"
      port: 4040

​
Peer-to-Peer Settings

FieldTypeDefaultDescription
ble_enabledboolean/nullnullEnable Bluetooth Low Energy connectivity
lan_enabledboolean/nullnullEnable LAN connectivity
lan_mdns_enabledboolean/nullnullEnable mDNS for automatic peer discovery on LAN
lan_multicast_enabledboolean/nullnullEnable multicast for LAN communication

​
Connect Configuration

Configure outbound connections to known servers:
FieldTypeDefaultDescription
known_tcp_serversarray[string][]List of TCP server addresses to connect to (format: "host:port")
known_ws_serversarray[string][]List of WebSocket server URLs to connect to
retry_interval_msecinteger/nullnullRetry interval in milliseconds (min: 0, max: 4294967295)

​
Listen Configuration

Configure inbound TCP connections:
FieldTypeDefaultDescription
tcp_listen.enableboolean/nullnullEnable TCP listener
tcp_listen.ipstring/nullnullIP address to bind to
tcp_listen.portinteger/nullnullPort number (0-65535)

​
Complete Examples

​
Cloud-Connected Database

resources:
  cloud_db:
    resource_type: DittoDatabase
    db_id: "12345678-1234-4123-1234-123456789012"
    device_name: "edge-gateway-01"
    auth:
      server:
        access_token: "your-playground-token"
        auth_url: "https://your-app.cloud.dittolive.app"
        provider: "__playgroundProvider"
        enable_cloud_sync: true
    persistence_dir:
      path: "./data/cloud_db"
    transport_config:
      peer_to_peer:
        lan_enabled: true
        lan_mdns_enabled: true

​
Offline Mesh Database

resources:
  mesh_db:
    resource_type: DittoDatabase
    db_id: "87654321-4321-4123-4321-210987654321"
    device_name: "mesh-node-01"
    auth:
      small_peer_only:
        offline_license_token: "your-offline-license"
    persistence_dir:
      path: "./data/mesh_db"
    transport_config:
      peer_to_peer:
        ble_enabled: true
        lan_enabled: true
        lan_mdns_enabled: true
        lan_multicast_enabled: true

​
Connect with Known Peers

resources:
  hub_db:
    resource_type: DittoDatabase
    db_id: "11111111-2222-4333-4444-555555555555"
    device_name: "central-hub"
    auth:
      small_peer_only:
        offline_license_token: "your-offline-license"
    transport_config:
      peer_to_peer:
        lan_mdns_enabled: false
      connect_config:
        known_tcp_servers:
          - "192.168.1.10:4040"
          - "192.168.1.11:4040"
        retry_interval_msec: 10000

​
Important Notes

  1. Database ID Uniqueness: Each db_id must be unique across all DittoDatabase resources in your configuration
  2. Device Name: The device_name helps identify this Edge Server instance in the mesh network. Choose descriptive names for easier debugging
  3. Multiple Databases: You can configure multiple DittoDatabase resources in a single Edge Server deployment, but they won’t communicate with each other
  4. Transport Defaults: When transport settings are null, Edge Server uses sensible defaults based on your platform and network environment
  5. Security: In production, always use proper authentication providers configured in the Ditto Portal rather than playground mode