Configuration
The evitaDB server is configured in YAML format and its default settings are best described by the following code snippet:
| Abbreviation | Meaning | Example |
|---|---|---|
| K | one thousand | 1K → 1,000 |
| M | one million | 1M → 1,000,000 |
| G | one billion | 1G → 1,000,000,000 |
| T | one trillion | 1T → 1,000,000,000,000 |
| Abbreviation | Meaning | Example |
|---|---|---|
| KB | one kilobyte | 1KB → 1,024 |
| MB | one megabyte | 1MB → 1,048,576 |
| GB | one gigabyte | 1GB → 1,073,741,824 |
| TB | one terabyte | 1TB → 1,099,511,627,776 |
| Abbreviation | Meaning | Example |
|---|---|---|
| 1s | one second | 1s → 1 secs |
| m | one minute | 1m → 60 secs |
| h | one hour | 1h → 3,600 secs |
| d | one day | 1d → 86,400 secs |
| d | one week | 1w → 604,800 secs |
| y | one year | 1y → 31,556,926 secs |
Name
Server configuration
This section contains general settings for the evitaDB server. It allows configuring thread pools, queues, timeouts:
- coreThreadCount
Default: 4
It defines the minimum number of threads in the evitaDB main thread pool, threads are used for query processing, transactional updates and service tasks (vacuuming, cache revalidation). The value should be at least equal to the number of machine cores.
- maxThreadCount
Default: 16
It defines the maximum number of threads in the evitaDB main thread pool. The value should be a multiple of the coreThreadCount value.
- threadPriority
Default: 5
It defines the priority of the threads created in the pool (for future use).
- queueSize
Default: 100
It defines the maximum number of tasks that can accumulate in the queue waiting for the free thread from the thread pool to process them. Tasks that exceed this limit will be discarded (new requests/other tasks will fail with an exception).
- shortRunningThreadsTimeoutInSeconds
Default: 1
It sets the timeout in seconds after which threads that are supposed to be short-running should timeout and cancel its execution.
- killTimedOutShortRunningThreadsEverySeconds
Default: 30
It sets an interval in seconds in which short-running timed out threads are forced to be killed (unfortunately, it's not guarantied that the threads will be actually killed) and stack traces are printed
- closeSessionsAfterSecondsOfInactivity
Default: 60
It specifies the maximum acceptable period of inactivity before it is forcibly closed by the server side.
- readOnly
Default: false
It switches the evitaDB server into read-only mode, where no updates are allowed and the server only provides read access to the data of the catalogs present in the data directory at the start of the server instance.
- quiet
Default: false
It disables logging of helper info messages (e.g.: startup info). Note that it doesn't disable the main logging handled by the Slf4j logging facade.
This setting should not be used when running multiple server instances inside single JVM because it is currently not thread-safe.
Storage configuration
This section contains configuration options for the storage layer of the database.
- storageDirectory
Default: null
It defines the folder where evitaDB stores its catalog data. The path can be specified relative to the working directory of the application in absolute form (recommended).
- lockTimeoutSeconds
Default: 60
It specifies the maximum amount of time the thread may wait to get an exclusive WRITE lock on the file to write its data. Changing this value should not be necessary if everything is going well.
- waitOnCloseSeconds
Default: 60
It specifies a timeout for evitaDB to wait for the release of read handles to a file. If the file handle is not released within the timeout, the calling process will get an exception. Changing this value should not be necessary if everything works fine.
- outputBufferSize
Default: 4MB
The output buffer size determines how large a buffer is kept in memory for output purposes. The size of the buffer limits the maximum size of an individual record in the key/value data store.
- maxOpenedReadHandles
Default: 12
It defines the maximum number of simultaneously opened file read handles.
- computeCRC32C
Default: true
It determines whether CRC32C checksums are calculated for written records in a key/value store, and also whether the CRC32C checksum is checked when a record is read.
It is strongly recommended that this setting be set to true, as it will report potentially corrupt records as early as possible.- minimalActiveRecordShare
Default: 0.5 (when waste exceeds 50% the file is compacted)
Minimal share of active records in the data file. If the share is lower and the file size exceeds also fileSizeCompactionThresholdBytes limit, the file will be compacted. It means new file containing only active records will be written next to original file.
- fileSizeCompactionThresholdBytes
Default: 100MB
Minimal file size threshold for compaction. If the file size is lower, the file will not be compacted even if the share of active records is lower than the minimal share.
Transaction configuration
This section contains configuration options for the storage layer of the database dedicated to transaction handling.
- transactionWorkDirectory
Default: /tmp/evitaDB/transaction
Directory on local disk where Evita creates temporary folders and files for transactional transaction. By default, temporary directory is used - but it is a good idea to set your own directory to avoid problems with disk space.
- transactionMemoryBufferLimitSizeBytes
Default: 16MB
Number of bytes that are allocated on off-heap memory for transaction memory buffer. This buffer is used to store temporary (isolated) transactional data before they are committed to the database. If the buffer is full, the transaction data are immediately written to the disk and the transaction processing gets slower.
- transactionMemoryRegionCount
Default: 256
Number of slices of the transactionMemoryBufferLimitSizeBytes buffer. The more slices the smaller they get and the higher the probability that the buffer will be full and will have to be copied to the disk.
- walFileSizeBytes
Default: 16MB
Size of the Write-Ahead Log (WAL) file in bytes before it is rotated.
- walFileCountKept
Default: 8
Number of WAL files to keep. Increase this number in combination with walFileSizeBytes if you want to keep longer history of changes.
- maxQueueSize
Default: 1K
Size of the catalog queue for parallel transaction. If there are more transaction than the number of free threads in the pool, the transaction are queued. If the queue is full, the transaction is rejected.
- flushFrequencyInMillis
Default: 1s
The frequency of flushing the transactional data to the disk when they are sequentially processed. If database process the (small) transaction very quickly, it may decide to process next transaction before flushing changes to the disk. If the client waits for WAIT_FOR_INDEX_PROPAGATION he may wait entire flushFrequencyInMillis milliseconds before he gets the response.
Cache configuration
The cache speeds up responses for fully or partially identical queries. The cache might in some case increase the throughput of the system several times.
- enabled
Default: true
This setting enables or disables the use of the cache entirely.
- reflection
Default: CACHE
This setting enables or disables caching of Java reflection information. The CACHE mode is usually recommended unless you're running some kind of test.
- reevaluateEachSeconds
Default: 60
It defines the period for re-evaluating cache adepts to be propagated to cache or pruned. The reevaluation may be also triggered by exceeding maximum allowed anteroomRecordCount, but no later than reevaluateEachSeconds since the last re-evaluation (with the exception when there is no free thread in thread pool to serve this task). See detailed caching process description.
- anteroomRecordCount
Default: 100K
It defines the maximum number of records in cache anteroom. When this count is reached the re-evaluation process is automatically triggered leading to anteroom purge. The anteroom is also periodically purged each reevaluateEachSeconds. See detailed caching process description.
- minimalComplexityThreshold
Default: 10K
It specifies the minimum computational complexity that must be achieved to store the cached result in the cache. It's sort of a virtual number, so there's no guide as to how big it should be. If the cache fills up with a lot of results of doubtful use, you might try to increase this threshold to higher values.
- minimalUsageThreshold
Default: 2
It specifies the minimum number of times a computed result can be reused before it is cached. If the cache is filling up with cached values with low hit ratios, you might try increasing this threshold to higher values.
- cacheSizeInBytes
Default: null, which means that evitaDB uses 25% of the free memory measured at the moment it starts and loads all data into it
evitaDB tries to estimate the memory size of each cached object and avoid exceeding this threshold.
Measuring the exact amount of memory each object allocates is not easy in Java, and at the moment it's only an approximation from our side. According to our experience, our estimates are set higher than the reality and the system stops at around 90% of the set cacheSizeInBytes limit (but this experience is based on OS Linux, x86_64 architecture).
API configuration
This section of the configuration allows you to selectively enable, disable, and tweak specific APIs.
- ioThreads
Default: 4
Defines the number of IO threads that will be used by Undertow for accept and send HTTP payload.
- exposedOn
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system. By specifying the exposedOn property you can specify the name (without port) of the host system host name that will be used by all API endpoints without specific exposedHost configuration property to use that host name and appropriate port.
- accessLog
Default: false
It enables / disables access log messages logging for all APIs.
TLS configuration
TLS support is enabled by default for most APIs but can be disabled individually per API in API configs. Note that if you set that each API has different TLS settings, each API must have its own port.
- generateAndUseSelfSigned
Default: true
When set to true, a self-signed certificate authorityToggle Term Reference certificateToggle Term Reference and its private keyToggle Term Reference are automatically generated on server startup and used to communicate with clients.
- folderPath
Default: the sub-folder evita-server-certificates in the working directory
It represents a path to a folder where the generated authority certificate and its private key are stored. This setting is used only when generateAndUseSelfSigned is set to true.
- custom
This section allows you to configure an externally supplied certificateToggle Term Reference. It is only used if the generateAndUseSelfSigned is set to false.
The section requires these nested settings:
- certificate: path to the public part of the certificate file (*.crt)
- privateKey: path to the private key of the certificate (*.key)
- privateKeyPassword: password for the private key
Tip
It is recommended to provide the private key password using command line argument (environment variable) api.certificate.custom.privateKeyPasssword and store id in a CI server secrets vault.Yes there is. You can use standardized way importing the certificate authorityToggle Term Reference certificateToggle Term Reference to the Java trust store. This procedure is described in great detail in this article.
If no custom certificate is configured, the server will not start and an exception will be thrown. The server doesn't provide an unsecured connection for security reasons.
GraphQL API configuration
- enabled
Default: true
It enables / disables GraphQL web API.
- host
Default: localhost:5555
It specifies the host and port that the GraphQL API should listen on. The value may be identical to the REST API, but not to the gRPC or System API.
- exposedHost
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system. If you specify this property, the exposeOn global property is no longer used.
- tlsEnabled
Default: true
Whether the TLS should be enabled for the GraphQL API. If multiple APIs share the same port, all such APIs need to have set the same tlsEnabled value, or each API must have its own port.
- allowedOrigins
Default: null
Specifies comma separated origins that are allowed to consume the GraphQL API. If no origins are specified, i.e. null, all origins are allowed automatically.
- parallelize
Default: true
Controls whether queries that fetch data from evitaDB engine will be executed in parallel.
REST API configuration
- enabled
Default: true
It enables / disables REST web API.
- host
Default: localhost:5555
It specifies the host and port that the GraphQL API should listen on. The value may be identical to the GraphQL API, but not to the gRPC or System API.
- exposedHost
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system. If you specify this property, the exposeOn global property is no longer used.
- tlsEnabled
Default: true
Whether the TLS should be enabled for the REST API. If multiple APIs share the same port, all such APIs need to have set the same tlsEnabled value, or each API must have its own port.
- allowedOrigins
Default: null
Specifies comma separated origins that are allowed to consume the GraphQL API. If no origins are specified, i.e. null, all origins are allowed automatically.
gRPC API configuration
- enabled
Default: true
It enables / disables gRPC web API.
- host
Default: localhost:5555
It specifies the host and port that the GraphQL API should listen on. The value must be different from all other APIs because gRPC internally uses completely different web server.
- exposedHost
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system. If you specify this property, the exposeOn global property is no longer used.
Mutual TLS configuration
- enabled
Default: true
It enables / disables mutual authentication.
- allowedClientCertificatePaths
Default: null
It allows you to define zero or more file paths pointing to public client certificatesToggle Term Reference. Only clients that present the correct certificate will be allowed to communicate with the gRPC web API.
System API configuration
- enabled
Default: true
It enables / disables system web API.
- host
Default: localhost:5557
It specifies the host and port on which the system API should listen. The value must be different from all other APIs because the system API needs to run on the insecure HTTP protocol while the other APIs use the secure one.
The system endpoint allows anyone to view public certificate authorityToggle Term Reference certificateToggle Term Reference and it also provides information for default mTLS implementation.
- tlsEnabled
Default: false
Whether the TLS should be enabled for the System API. If multiple APIs share the same port, all such APIs need to have set the same tlsEnabled value, or each API must have its own port.
- allowedOrigins
Default: null
Specifies comma separated origins that are allowed to consume the GraphQL API. If no origins are specified, i.e. null, all origins are allowed automatically.
evitaLab configuration
- enabled
Default: true
It enables / disables evitaLab API.
- host
Default: localhost:5555
It specifies the host and port that the evitaLab API/evitaLab web client should listen on. The value may be identical to the GraphQL API and REST API, but not to the gRPC or System API.
- exposedHost
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system. If you specify this property, the exposeOn global property is no longer used.
- tlsEnabled
Default: true
Whether the TLS should be enabled for the evitaLab API/evitaLab web client. If multiple APIs share the same port, all such APIs need to have set the same tlsEnabled value, or each API must have its own port.
- allowedOrigins
Default: null
Specifies comma separated origins that are allowed to consume the evitaLab API/evitaLab web client. If no origins are specified, i.e. null, all origins are allowed automatically.
- gui
GUI configuration
This configuration controls how the actual evitaLab web client will be served through HTTP protocol.
- enabled
Default: true
Whether evitaDB should serve the built-in evitaLab web client alongside the evitaLab API.
- readOnly
Default: false
Whether the evitaLab web client should be served in read-only mode. This means that it's runtime data and configuration cannot be changed. It doesn't mean that it will not allow you to change the data of an accessed evitaDB instance. This must be configured at the scope of the evitaDB instance.
- preconfiguredConnections
Default: null
It allows passing a list of evitaDB connections to the web client. These connections will be ready to use by a user of the web client. By default (when null is passed), evitaDB will pass itself as a preconfigured connection for quick access. This can be disabled by passing empty list, or it can be completely overridden by passing a custom list of connections.
It accepts either a path to YAML file prefixed with !include with a list of connections, or a list of connections directly in the main configuration. A single connection can be defined as follows:This is especially useful for when the evitaDB server is running locally on a server behind a reverse proxy and it is exposed on a different public domain and port, not on a localhost. Without custom connection configuration pointing to the public domain, the evitaLab web client would try to connect to the server on localhost.