Database
database.conf configures how the Enterprise API stores organizations, tenants, services, keys, sessions, and related data.
MongoDB is the supported production driver. Amazon DocumentDB, Azure Cosmos DB for MongoDB, and DocumentDB on PostgreSQL (which includes Azure DocumentDB) are supported through database profiles that disable MongoDB features those engines do not implement fully. DocumentDB on PostgreSQL is described in DocumentDB Deployment. Vanilla PostgreSQL, which does not use the MongoDB wire protocol, is a separate databaseType below.
Select the profile that matches the backend and do not leave the default profile = MONGODB_8 on a non-MongoDB engine. The profile decides whether the API reads cursors and creates collections and indexes inside transactions, and whether it may send a collation.
Example File
databaseType = mongodb
mongodb = {
# Refer to https://www.mongodb.com/docs/manual/reference/connection-string/
connectionString = "mongodb://root:password@mongodb:27017/?&replicaSet=rs0"
# For engines without retryable writes (DocumentDB on PostgreSQL, Amazon DocumentDB before 8.0.2), set retryWrites=false.
# connectionString = "mongodb://root:password@localhost:27017?replicaSet=rs0&directConnection=true&retryWrites=false"
# Connection String quick reference:
# - if username/password contain special characters, they must be converted with percent encoding (RFC3986 2.1)
#
# Format: mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]
#
# EXAMPLES:
#
# Standard:
# 1. Standalone: mongodb://user:password@host:port/
# 2. Shared cluster: mongodb://user:password@host1:port1,host2:port2,host3:port3/ (`mongos` hosts in connection string)
# 3. Replica set: mongodb://user:password@host1:port1,host2:port2,host3:port3/?&replicaSet=replicaSetName
#
# SRV format (see https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-dns-seedlist)
# "DNS-constructed seed list to construct available servers list"
# Examples: same as above, with `mongodb+srv://` instead of `mongodb://`
database = "waltid-enterprise"
# Database profile - determines feature capabilities
# Options:
# MongoDB: MONGODB_5, MONGODB_6, MONGODB_7, MONGODB_8 (recommended)
# AWS DocumentDB: AWS_DOCUMENTDB_4, AWS_DOCUMENTDB_5, AWS_DOCUMENTDB_8
# Azure Cosmos DB (RU-based): AZURE_COSMOSDB_4, AZURE_COSMOSDB_6, AZURE_COSMOSDB_7
# DocumentDB on PostgreSQL, including Azure DocumentDB: DOCUMENTDB_POSTGRES
# Custom: CUSTOM (requires dbFeatures configuration)
profile = MONGODB_8
# Optional: Override collation from profile (set to "none" to disable)
# collation = "en"
# Only used when profile = CUSTOM
# dbFeatures = {
# cursorWithinTransaction = true
# collationSupported = true
# multiDocumentTransactions = true
# ddlOperationsInTransaction = true
# }
pool = {
maxSize = 100
minSize = 10
maxWaitTimeMs = 5000
maxConnectionIdleTimeMs = 60000
maxConnectionLifeTimeMs = 1800000
}
ssl = {
enable = false
trustStoreLocation = ""
trustStorePassword = ""
invalidHostNameAllowed = false
keyStoreLocation = ""
keyStorePassword = ""
keyPassword = ""
}
}
Startup logs print the selected profile and its capability flags, for example Using database profile: MongoDB 8.0.
Fields
databaseType
String — Storage driver. Production deployments use mongodb.
mongodb.connectionString
String — MongoDB connection URI, including credentials, hosts, and driver options.
- Percent-encode special characters in the username and password (RFC 3986).
- Append options as query parameters, for example
&readPreference=secondaryPreferred. - Engines without retryable writes require
retryWrites=falseon the URI: DocumentDB on PostgreSQL and Amazon DocumentDB before 8.0.2.
mongodb.database
String — Database name on the server. Default in the example is "waltid-enterprise".
mongodb.profile
String — Selects which MongoDB-compatible features the API will use. Default is MONGODB_8.
| Profile | Use when | Collation Allowed | Cursors in transactions | DDL in transactions |
|---|---|---|---|---|
MONGODB_5, MONGODB_6, MONGODB_7, MONGODB_8 | Native MongoDB | Yes | Yes | Yes |
AWS_DOCUMENTDB_4, AWS_DOCUMENTDB_5, AWS_DOCUMENTDB_8 | Amazon DocumentDB | No | No | No |
AZURE_COSMOSDB_4, AZURE_COSMOSDB_6, AZURE_COSMOSDB_7 | Azure Cosmos DB for MongoDB (RU-based) | No | No | No |
DOCUMENTDB_POSTGRES | DocumentDB on PostgreSQL, including Azure DocumentDB | No | Yes | Yes |
CUSTOM | You set dbFeatures yourself | From dbFeatures | From dbFeatures | From dbFeatures |
The AZURE_COSMOSDB_* profiles are for Azure Cosmos DB for MongoDB (RU-based). Azure DocumentDB, formerly Azure Cosmos DB for MongoDB vCore, runs the DocumentDB engine and uses DOCUMENTDB_POSTGRES. For Amazon DocumentDB and Azure Cosmos DB, pick the profile that matches the server version you run.
DOCUMENTDB_POSTGRES is for the open-source DocumentDB engine on PostgreSQL, which is a different product from Amazon DocumentDB. Cursors work inside a transaction, so do not use an AWS_DOCUMENTDB_* profile for it. The engine does not support change streams or collation.
The Amazon DocumentDB and Azure Cosmos DB profiles read outside the transaction session and create collections and indexes outside transactions.
mongodb.collation
String, optional — Locale used for sorted find queries when the profile supports collation.
- If omitted, no collation is sent. No profile sets a default.
- Set a locale to send it on sorted finds, if the profile allows collation. Set
"none"or""to send none. - A collation that differs from the one the indexes were created with stops MongoDB using index bounds for string comparisons. If you set one, create matching collation-aware indexes.
- walt.id does not require MongoDB
simplecollation, collection default collation, or locale-aware unique indexes. - Collation is attached only to sorted finds. Inserts, updates,
findOneAndDelete, index creation, and collection creation do not send a collation document.
Do not set collation on Amazon DocumentDB, Azure Cosmos DB, or DocumentDB on PostgreSQL: collation coverage on those engines is partial.
mongodb.dbFeatures
Object — Used only when profile = CUSTOM.
| Field | Default | Description |
|---|---|---|
cursorWithinTransaction | true | Whether getMore / cursors work inside a transaction |
collationSupported | true | Whether sorted finds may include a collation document |
multiDocumentTransactions | true | Whether multi-document transactions are available |
ddlOperationsInTransaction | true | Whether collections and indexes may be created inside a transaction |
mongodb.pool
Object — MongoDB driver connection pool. Defaults are shown in the example.
| Field | Default | Description |
|---|---|---|
maxSize | 100 | Maximum connections in the pool |
minSize | 10 | Minimum warm connections |
maxWaitTimeMs | 5000 | How long to wait for a connection before failing |
maxConnectionIdleTimeMs | 60000 | Idle connection lifetime (1 minute) |
maxConnectionLifeTimeMs | 1800000 | Maximum connection lifetime (30 minutes) |
mongodb.ssl
Object — TLS settings for the MongoDB connection.
| Field | Description |
|---|---|
enable | Set true to use TLS |
trustStoreLocation | Path to a JKS trust store |
trustStorePassword | Trust store password |
invalidHostNameAllowed | When false (recommended in production), the certificate hostname must match the server |
keyStoreLocation | Optional JKS key store for mTLS |
keyStorePassword | Key store password |
keyPassword | Password for the private-key entry. Defaults to keyStorePassword when omitted |
TLS settings are only read from this block: tlsInsecure in the connection string is ignored, so a gateway with a self-signed certificate needs its certificate in the trust store. Keep exactly one ssl block in the configuration.
An AWS trust store is bundled as config/aws-truststore.jks with password 123456. Replace it with your own trust store in production.
Docker and JVM overrides can set these properties without editing the file, for example -Dconfig.override.mongodb.ssl.enable=true. The same pattern works for mongodb.profile.
Vanilla PostgreSQL
databaseType = postgresql stores the same documents as JSONB in one table per collection. It does not speak the MongoDB wire protocol and it is not DocumentDB. There is no migration from an existing MongoDB database. PostgreSQL 18 is the tested version. See PostgreSQL Deployment for setup and limits.
databaseType = postgresql
postgresql = {
connectionString = "jdbc:postgresql://postgres:5432/waltid_enterprise"
username = "waltid"
password = "waltid"
recreateOnStart = false
}
- Point every API replica at the primary. A hot standby is refused. A transaction-mode pooler such as PgBouncer needs
prepareThreshold=0on the JDBC URL. - The pool default is 24. A request can hold two connections, so
maxSizetimes the number of replicas, times two, must stay undermax_connections. - Licensing requires
usageCheckpointEngine = true. The reservation engine is refused. ssl.enable = trueaddssslmode=require. For certificate verification, setsslmode=verify-fulland the certificate files on the JDBC URL. JKS trust-store fields are rejected.recreateOnStartdeletes application and license data and is refused unless dev-mode is on or-Dwalt.postgres.allowRecreateOnStart=true.
