DataStore

Configures the primary data store backend.

This object can be configured from the WebUI under Settings › Storage › Data Store

Fields

DataStore is a multi-variant object: each instance has an @type discriminator selecting one of the variants below, and each variant carries its own set of fields.

`@type: "RocksDb"`

RocksDB

`path`

Type: String · required

Path to the RocksDB data directory

`blobSize`

Type: Size · default: 4096 · max: 1048576 · min: 1024

Minimum size of a blob to write to a separate RocksDB blob file; smaller blobs are stored inline in the LSM tree. Only applies when RocksDB is also the blob store

`bufferSize`

Type: Size · default: 134217728 · max: 4294967296 · min: 8388608

Total amount of memory shared by the write buffers (memtables) of every column family. Higher values batch more writes in memory before they are flushed to disk

`poolWorkers`

Type: UnsignedInt? · max: 64 · min: 1

Number of worker threads to use for the store, defaults to the number of cores

`cacheSize`

Type: Size? · max: 17179869184 · min: 8388608

Total amount of memory shared by the block caches of every column family, used to cache data blocks, indexes and bloom filters read from disk. When unset, one eighth of the memory available to the server (the lower of physical memory and the container memory limit), between 256 MiB and 8 GiB; on hosts with less than 1 GiB, a quarter of the memory; 256 MiB when the memory cannot be determined

`@type: "Sqlite"`

SQLite

`path`

Type: String · required

Path to the SQLite data directory

`poolWorkers`

Type: UnsignedInt? · max: 64 · min: 1

Number of worker threads to use for the store, defaults to the number of cores

`poolMaxConnections`

Type: UnsignedInt? · max: 8192 · min: 1

Maximum number of connections to the store. When unset, the number of worker threads, between 4 and 16.

`@type: "FoundationDb"`

FoundationDB

`clusterFile`

Type: String?

Path to the cluster file for the FoundationDB cluster

`datacenterId`

Type: String?

Data center ID (optional)

`machineId`

Type: String?

Machine ID in the FoundationDB cluster (optional)

`transactionRetryDelay`

Type: Duration?

Transaction maximum retry delay

`transactionRetryLimit`

Type: UnsignedInt? · max: 1000 · min: 1

Transaction retry limit

`transactionTimeout`

Type: Duration?

Transaction timeout

`@type: "PostgreSql"`

PostgreSQL

`connectTimeout`

Type: Duration? · default: 15000

Maximum time to wait for a connection to the database server to be established

`useTls`

Type: Boolean · default: false

Use TLS to connect to the store

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

`poolMaxConnections`

Type: UnsignedInt? · max: 8192 · min: 1

Maximum number of connections to the store. When unset, 4 per CPU core, between 16 and 32.

`poolRecyclingMethod`

Type: PostgreSqlRecyclingMethod · default: "fast"

Method to use when recycling connections in the pool

`readReplicas`

Type: List<PostgreSqlSettings> · enterprise

List of read replicas for the store

`host`

Type: String · required

Hostname of the database server

`port`

Type: UnsignedInt · default: 5432 · max: 65535 · min: 1

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

`options`

Type: String?

Additional connection options

`@type: "MySql"`

mySQL

`idleTimeout`

Type: Duration? · default: 15000

Time an idle connection may stay open before the server closes it (sets the MySQL wait_timeout session variable)

`useTls`

Type: Boolean · default: false

Use TLS to connect to the store

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

`maxAllowedPacket`

Type: UnsignedInt? · max: 1073741824 · min: 1024

Maximum size of a packet in bytes

`poolMaxConnections`

Type: UnsignedInt? · max: 8192 · min: 1

Maximum number of connections to the store. When unset, 4 per CPU core, between 16 and 32.

`poolMinConnections`

Type: UnsignedInt? · default: 5 · max: 8192 · min: 1

Minimum number of connections to the store

`readReplicas`

Type: List<MySqlSettings> · enterprise

List of read replicas for the store

`host`

Type: String · required

Hostname of the database server

`port`

Type: UnsignedInt · default: 3306 · max: 65535 · min: 1

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

JMAP API

The DataStore singleton is available via the urn:stalwart:jmap capability.

`x:DataStore/get`

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

For singletons, the ids argument should be the literal singleton (or null to return the single instance).

This method requires the sysDataStoreGet permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DataStore/get",
          {
            "ids": [
              "singleton"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

`x:DataStore/set`

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

For singletons, only the update argument with id singleton is accepted; create and destroy arguments are rejected.

This method requires the sysDataStoreUpdate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DataStore/set",
          {
            "update": {
              "singleton": {
                "path": "updated value"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get DataStore

Update

stalwart-cli update DataStore --field path='updated value'

Nested types

PostgreSqlSettings

PostgreSQL connection settings.

`host`

Type: String · required

Hostname of the database server

`port`

Type: UnsignedInt · default: 5432 · max: 65535 · min: 1

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

`options`

Type: String?

Additional connection options

SecretKeyOptional

An optional secret value, or none.

None: No secret. No additional fields.
Value: Secret value. Carries the fields of SecretKeyValue.
EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
File: Secret read from file. Carries the fields of SecretKeyFile.

SecretKeyValue

A secret value provided directly.

`secret`

Type: String · required · secret

Password or secret value

SecretKeyEnvironmentVariable

A secret value read from an environment variable.

`variableName`

Type: String · required

Environment variable name to read the secret from

SecretKeyFile

A secret value read from a file.

`filePath`

Type: String · required

File path to read the secret from

MySqlSettings

MySQL connection settings.

`host`

Type: String · required

Hostname of the database server

`port`

Type: UnsignedInt · default: 3306 · max: 65535 · min: 1

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

Enums

PostgreSqlRecyclingMethod

Value	Label
`fast`	Fast recycling method
`verified`	Verified recycling method
`clean`	Clean recycling method