DittoDatabase Resource Configuration

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

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

Required Fields

Field	Type	Description
`db_id`	string	Unique database identifier in UUIDv4 format (e.g., `"12345678-1234-4123-1234-123456789012"`)
`device_name`	string	Edge server device name on the mesh (minimum 1 character)
`auth`	object	Authentication 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: "REPLACE_ME_WITH_YOUR_URL"
    provider: "__playgroundProvider"  # or your custom webhook provider
    enable_cloud_sync: true  # Optional, defaults to true

Field	Type	Required	Description
`access_token`	string	Yes	Token used to authenticate with the authentication provider
`auth_url`	string (URL)	Yes	Authentication URL for cloud sync
`provider`	string	Yes	Webhook provider configured in Ditto Portal. Use `"__playgroundProvider"` for development/playground mode
`enable_cloud_sync`	boolean	No	Enable automatic cloud synchronization (default: `true`)

Ditto SDK Devices (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

Field	Type	Required	Description
`offline_license_token`	string	Yes	Offline license token for SmallPeerOnly mode
`key_b64`	string	No	Optional base64-encoded key for shared key encryption

Optional Configuration

Auto-Fetch Attachments

Control whether the database automatically fetches new attachments from other peers:

auto_fetch_attachments: false  # Default

Field	Type	Default	Description
`auto_fetch_attachments`	boolean	`false`	Set to `true` to automatically fetch new attachments from other peers without requiring explicit client requests

Automatically fetching attachments will incur a performance cost in both network and disk usage. Only enable this if your application requires immediate attachment synchronization.

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

Field	Type	Default	Description
`ble_enabled`	boolean/null	null	Enable Bluetooth Low Energy connectivity
`lan_enabled`	boolean/null	null	Enable LAN connectivity
`lan_mdns_enabled`	boolean/null	null	Enable mDNS for automatic peer discovery on LAN
`lan_multicast_enabled`	boolean/null	null	Enable multicast for LAN communication

Connect Configuration

Configure outbound connections to known servers:

Field	Type	Default	Description
`known_tcp_servers`	array[string]	`[]`	List of TCP server addresses to connect to (format: `"host:port"`)
`known_ws_servers`	array[string]	`[]`	List of WebSocket server URLs to connect to
`retry_interval_msec`	integer/null	null	Retry interval in milliseconds (min: 0, max: 4294967295)

Listen Configuration

Configure inbound TCP connections:

Field	Type	Default	Description
`tcp_listen.enable`	boolean/null	null	Enable TCP listener
`tcp_listen.ip`	string/null	null	IP address to bind to
`tcp_listen.port`	integer/null	null	Port number (0-65535)

Important Notes

Device Name: The device_name helps identify this Edge Server instance in the mesh network. Choose descriptive names for easier debugging
Transport Defaults: When transport settings are null, Edge Server uses sensible defaults based on your platform and network environment
Security: In production, always use proper authentication providers configured in the Ditto Portal rather than playground mode

Ditto Edge Server

Getting Started

Reference

DittoDatabase Resource Configuration

Basic Configuration

Required Fields

Authentication Methods

Cloud/Server Authentication

Ditto SDK Devices (Small Peer Only) Mode

Optional Configuration

Auto-Fetch Attachments

Subscriptions

Persistence Directory

Transport Configuration

Peer-to-Peer Settings

Connect Configuration

Listen Configuration

Important Notes

​Basic Configuration

​Required Fields

​Authentication Methods

​Cloud/Server Authentication

​Ditto SDK Devices (Small Peer Only) Mode

​Optional Configuration

​Auto-Fetch Attachments

​Subscriptions

​Persistence Directory

​Transport Configuration

​Peer-to-Peer Settings

​Connect Configuration

​Listen Configuration

​Important Notes

Basic Configuration

Required Fields

Authentication Methods

Cloud/Server Authentication

Ditto SDK Devices (Small Peer Only) Mode

Optional Configuration

Auto-Fetch Attachments

Subscriptions

Persistence Directory

Transport Configuration

Peer-to-Peer Settings

Connect Configuration

Listen Configuration

Important Notes