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
| Field | Type | Description |
|---|
resource_type | string | Must be "DittoDatabase" |
db_id | string | Unique database identifier in UUIDv4 format (e.g., "12345678-1234-4123-1234-123456789012"). Must be unique across all DittoDatabase resources in the config |
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: "https://YOUR-AUTH-URL.cloud.dittolive.app"
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) |
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"
- 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
"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
- Database ID Uniqueness: Each
db_id must be unique across all DittoDatabase resources in your configuration
- Device Name: The
device_name helps identify this Edge Server instance in the mesh network. Choose descriptive names for easier debugging
- Multiple Databases: You can configure multiple DittoDatabase resources in a single Edge Server deployment, but they won’t communicate with each other
- 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
