> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# DittoDatabase Resource Configuration

> Configure a Ditto database instance with mesh networking and optional cloud sync capabilities

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

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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 |

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

### Subscriptions

Define DQL subscriptions to register with this database:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

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