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

database.conf
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=false on 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.

ProfileUse whenCollation AllowedCursors in transactionsDDL in transactions
MONGODB_5, MONGODB_6, MONGODB_7, MONGODB_8Native MongoDBYesYesYes
AWS_DOCUMENTDB_4, AWS_DOCUMENTDB_5, AWS_DOCUMENTDB_8Amazon DocumentDBNoNoNo
AZURE_COSMOSDB_4, AZURE_COSMOSDB_6, AZURE_COSMOSDB_7Azure Cosmos DB for MongoDB (RU-based)NoNoNo
DOCUMENTDB_POSTGRESDocumentDB on PostgreSQL, including Azure DocumentDBNoYesYes
CUSTOMYou set dbFeatures yourselfFrom dbFeaturesFrom dbFeaturesFrom 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 simple collation, 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.

FieldDefaultDescription
cursorWithinTransactiontrueWhether getMore / cursors work inside a transaction
collationSupportedtrueWhether sorted finds may include a collation document
multiDocumentTransactionstrueWhether multi-document transactions are available
ddlOperationsInTransactiontrueWhether collections and indexes may be created inside a transaction

mongodb.pool

Object — MongoDB driver connection pool. Defaults are shown in the example.

FieldDefaultDescription
maxSize100Maximum connections in the pool
minSize10Minimum warm connections
maxWaitTimeMs5000How long to wait for a connection before failing
maxConnectionIdleTimeMs60000Idle connection lifetime (1 minute)
maxConnectionLifeTimeMs1800000Maximum connection lifetime (30 minutes)

mongodb.ssl

Object — TLS settings for the MongoDB connection.

FieldDescription
enableSet true to use TLS
trustStoreLocationPath to a JKS trust store
trustStorePasswordTrust store password
invalidHostNameAllowedWhen false (recommended in production), the certificate hostname must match the server
keyStoreLocationOptional JKS key store for mTLS
keyStorePasswordKey store password
keyPasswordPassword 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.

database.conf
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=0 on the JDBC URL.
  • The pool default is 24. A request can hold two connections, so maxSize times the number of replicas, times two, must stay under max_connections.
  • Licensing requires usageCheckpointEngine = true. The reservation engine is refused.
  • ssl.enable = true adds sslmode=require. For certificate verification, set sslmode=verify-full and the certificate files on the JDBC URL. JKS trust-store fields are rejected.
  • recreateOnStart deletes application and license data and is refused unless dev-mode is on or -Dwalt.postgres.allowRecreateOnStart=true.
Last updated on November 5, 2026