Configuration parameters

This chapter shows how to configure your Raijin installation.

raijin.conf

By default, the system reads its configuration from the /opt/raijin/data/conf/raijin.conf file which contains several configuration groups.

Logging settings

PanicMode

Specifies the way of handling critical errors. The available values are as follows:

  • HARD logs an error and stops the server

  • SOFT logs and throws an error

  • NONE logs and continues execution

LogFile

Specifies the filename to write Raijin logs to. The value assigned to LogFile is appended with a serial number which specifies the log file number in the sequence. The name of the current log file (the newest one) does not contain a suffix. Numbers from 1 to LogFileMaxCount - 1 are added to the names of older files․ The oldest log file is the one with LogFileMaxCount - 1 number added. When current log file size reaches LogFileMaxSize log rotation starts. During rotation every file is renamed to increase its suffix number by one and a new empty file named LogFile is created. This new file starts to receive recent entries.

Example of log file names:

/opt/raijin/log/raijin.log

/opt/raijin/log/raijin.log.1

/opt/raijin/log/raijin.log.8192

LogToSTDOUT

Specifies if the server should log to STDOUT.

In daemon mode, the server has no controlling terminal, so the parameter is ignored.
LogToSTDERR

Specifies if the server should log to STDERR.

In daemon mode, the server has no controlling terminal, so the parameter is ignored.
LogQueries

Specifies whether to write queries in the log file. The default is FALSE.

LogFileMaxSize

Specifies the maximum size of any single log file. The minimum value is 1 MB. The default value is set to 100 MB. Reaching LogFileMaxSize for current log file triggers the log rotation procedure. Rotation procedure described adove in the LogFile directive item.

The default value of 100 Mb may be too large for some environments. Please consider adjusting this value accordingly.
LogFileMaxCount

Specifies the maximum log file count that Raijin will maintain while running. The minimum value is 1. The default value is 5. If, after the rotation procedure, the number of log files exceeds LogFileMaxCount, the oldest file will be deleted. It means that Raijin will only maintain as many as LogFileMaxCount newest files.

Be careful when decreasing this value! If current total number of log files exceeds LogFileMaxCount, Raijin will remove all files with suffix numbers greater than LogFileMaxCount - 1 on its start.
LogLevels

Defines severity levels for various subsystems. The available values are DEBUG, INFO, WARNING, ERROR, CRITICAL.

These log levels are applicable to the following subsystems:

  • CommonLogLevel

  • StorageLogLevel

  • ParserLogLevel

  • OptimizerLogLevel

  • ExecutorLogLevel

  • AccessLogLevel

  • ServerLogLevel

  • GlobalLogLevel

If the XXXLogLevel is set, it uses its own value. Otherwise, it uses the value of the GlobalLogLevel.

Audit logging settings

EnableAuditLogging

A Boolean value, TRUE or FALSE, turns on and off audit logging functionality. The default value is FALSE.

AuditLogFile

Specifies the filename to write Raijin audit logs. The value assigned to AuditLogFile is appended with a serial number specifying the sequence’s log file number. The name of the current log file (the newest one) does not contain a suffix. Numbers from 1 to AuditLogFileMaxCount - 1 are added to the names of older files. The oldest log file is the one with AuditLogFileMaxCount - 1 number added. Log rotation starts when the current log file size reaches AuditLogFileMaxSize. During rotation, every file is renamed to increase its suffix number by one, and a new empty file named AuditLogFile is created. This new file starts to receive recent entries.

Example of log file names:

/opt/raijin/log/raijin_audit.log

/opt/raijin/log/raijin_audit.log.1

/opt/raijin/log/raijin_audit.log.8192

AuditLogFileMaxSize

Specifies the maximum size of any single audit log file. The minimum value is 1 MB. The default value is 100 MB. Reaching AuditLogFileMaxSize for the current log file triggers the log rotation procedure. The rotation procedure described above is in the AuditLogFile directive item.

The default value of 100 MB may be too large for some environments. Consider adjusting this value accordingly.
AuditLogFileMaxCount

Specifies the maximum audit log file count Raijin will maintain while running. The minimum value is 1. The default value is 5. If, after the rotation procedure, the number of log files exceeds AuditLogFileMaxCount, the oldest file will be deleted. It means that Raijin will only maintain as many as AuditLogFileMaxCount newest files.

Networking settings

ListenAddr

The address the server accepts connections on.

Port

The port the server accepts connections on.

KeepAliveTimeout

Timeout, in seconds, for HTTP(S) persistent connections in Raijin. If no data is sent over a connection for this amount of time, Raijin will close the connection. The minimum value is 1 second. The default value is 10 seconds.

Increasing this value allows connections to remain open through longer periods of inactivity, improving performance for persistent connections that periodically send data. However, a higher timeout also requires additional resources to keep connections open. So the value should be set high enough to maintain active connections, but not excessively high so that resources are used efficiently.

WebDir

The location of web front-end available at http://LocalAddr:Port.

Authentication settings

AuthenticationType

Indicates the type of authentication required to access Raijin. The possible values are as follows:

  • SSL: Raijin will use TLS/SSL for authentication, using the configuration defined in the SSL settings section.

  • PASSWORD: Authentication will be carried out with a password.

  • NONE: No authentication required - anyone can access Raijin. This setting can be used during development or testing to speed up access, but it’s not recommended in production environments.

SSL settings

CertFile

Server certificate filename. This parameter must be properly set for Raijin to operate in SSL mode.

CertKeyFile

Server private key filename. This parameter must be properly set for Raijin to operate in SSL mode.

CAFile

Certificate authority certificate filename. This parameter must be properly set for Raijin to validate client certificates.

DHFile

An optional directive specifies a file with dh-parameters for Diffie-Hellman key exchange. These parameters can be generated with dhparam(1ssl). If this directive is not specified, default parameters will be used. See the OpenSSL Wiki for details.

Storage settings

MemTableSize

Specifies the threshold for the memory table which stores new records. When the threshold is exceeded, the records are dumped to a file on disk. The size is measured in memory units.

DataFileSize

Specifies the threshold for the file containing table records. When the threshold is exceeded, a new file is created to store the new records. The size is measured in memory units.

ChunkSize

When storing column data on disk, the data is divided into several chunks. This parameter specifies the maximum number of items that a chunk can hold. Values less than or equal to 4096 are recommended. Values greater than 4096 can negatively affect server performance.

DescriptorFileCacheMaxSize

The maximum size in bytes of the descriptor file cache. This specifies the overall maximum; the cache contains a number of shards, and the maximum for each shard is calculated by dividing the DescriptorFileCacheMaxSize value by the number of shards. The number of shards is equal to the number of hardware threads that the system supports.

DataDir

The root data directory where Raijin stores databases. By default, it is set to /opt/raijin/data/db.

Prior to Raijin Database Engine 1.5 the default path was /opt/raijin/data. Take care when upgrading from an older version to Raijin Database Engine 1.5.
ControlFile

The path and name of the main database state file. Its content is used to determine whether the database was cleanly stopped. The loss of the control file will result in the database contents becoming unavailable. By default, it is set to /opt/raijin/data/db/raijin.control.

Prior to Raijin Database Engine 1.5 the default path was /opt/raijin/data. Take care when upgrading from an older version to Raijin Database Engine 1.5.`

Data encryption

keyring_type

The type of keyring to use. The supported values are FILE and FILE_ENCRYPTED.

keyring_file

The path of the keyring file when using a file-based keyring.

keyring_password

The password for the specified keyring. Required when the keyring type is FILE_ENCRYPTED.

Sorting and grouping settings

SortMemoryLimit

The maximum amount of memory to be used by a single Order By or Group By operation.

TmpDir

The directory to store intermediate results. If not set, the system temporary directory is used.

If not specified manually, the directory is cleaned from files unexpectedly left behind at each server start.

Conversion settings

HeapTypeConversion

Force data type conversion for heap columns (if schema is known in advance) respectively.

HeapTypeConversionRaiseError

If the given value can not be converted to the expected data type, an error is thrown if set to TRUE or ignored with the FALSE setting.

JsonAutoConvertType

If set to TRUE, JSON-formatted values are converted to primitives.

TransformNullEquals

If set to TRUE, equivalence checks (=, !=, <, >) work for NULL values as well.

Floating point representation settings

FloatPrecision

Sets the number of digits printed after the right of decimal point for float/double values. The default value is 6. The maximum value for DOUBLE is 17, for FLOAT this is 9. As server starts, this value is checked for the DOUBLE maximum only, but using values greater than 9 for FLOAT will abort the query execution with the runtime error.

Execution settings

PidFile

The location of the pid file used to stop the server in daemon mode. By default, it is set to /opt/raijin/run/.

User and Group

If not set, the current user and group are used. Otherwise, it uses the specified user:group and, if necessary, narrows privileges to it.

After the default installation, the raijin user and group are created and set as the owner of all server data. The User and Group parameters are also set to raijin.

MemoryReleaseInterval

Specifies the interval in milliseconds to release all unused memory back to the system. This is a resource-intensive operation; therefore, releasing memory too often may result in performance degradation. The default is 1000 milliseconds.

MemoryReleaseRate

Controls the rate at which unused memory is released back to the system. Increase this value to reduce memory usage and decrease it for faster memory allocation. Reasonable rates are in the 500 - 2000 range. The default value is 1250.0.

MaxConnections

Specifies the maximum number of asynchronous I/O threads, which determines the maximum number of asynchronous users that Raijin can serve. If not set, the default value is deduced at runtime from the underlying hardware.

WorkerThreads

The size of an internal tread pool used for parallel computations. The threads are shared between connections, so it represents the total maximum. If not set, the default value is deduced at runtime from the underlying hardware.

StackSize

Specifies the maximum size of each working thread. If not set, the system default is used.

StackOverflowLimit

The stack size limit at which the process execution will be aborted. The value of this parameter should indicate the minimum size of free memory in the stack. This free memory is needed for stack unwinding while generating the backtrace and correct termination of the process. The default value is 15Kb.

Operators policy settings

Raijin has the following types of operator behavior:

  • NULLING means that before calculating operator result its inputs are checked for irrelevant values. In case of incorrect values, they will be nulled

  • QUIET implies that no checks are performed and no errors are reported in case of invalid data presence

  • SIGNALING type of behavior means that before calculating operator result its inputs are checked for irrelevant values. In case of incorrect values, the process of calculation is aborted with an error message

Not all operators support policy behavior.

Below is the list of operators which support policy behavior.

OperatorPolicyGlobal

Sets a global policy. If the operator policy is set, it uses its own value. Otherwise, it uses this operator value. If the operator does not support policy that is set in OperatorPolicyGlobal then operator’s default is used.

OperatorAddPolicy

Addition operator (a + b) policy. The supported values are DEFAULT, QUIET, NULLING, and SIGNALING. The default value is QUIET.

OperatorMultiplyPolicy

Multiplication operator (a * b) policy. The supported values are DEFAULT, QUIET, NULLING, and SIGNALING. The default value is QUIET.

OperatorSubtractPolicy

Subtraction operator (a - b) policy. The supported values are DEFAULT, QUIET, NULLING, and SIGNALING. The default value is QUIET.

OperatorDividePolicy

Division operator (a / b) policy. The supported values are DEFAULT, QUIET, NULLING, and SIGNALING. The default value is QUIET.

OperatorModulusPolicy

Modulus operator (a % b; mod(a, b)) policy. The supported values are DEFAULT, NULLING, and SIGNALING. The default value is NULLING.

OperatorLnPolicy

Ln operator (Ln(a); Log(a)) policy. The supported values are DEFAULT, QUIET, and NULLING. The default value is QUIET.

OperatorLogPolicy

Log operator (Log(a, b)) policy. The supported values are DEFAULT, QUIET, and NULLING. The default value is QUIET.

OperatorLog10Policy

Log10 operator (Log10(a)) policy. The supported values are DEFAULT, QUIET, and NULLING. The default value is QUIET.

OperatorLog2Policy

Log2 operator (Log2(a)) policy. The supported values are DEFAULT, QUIET, and NULLING. The default value is QUIET.

OperatorSqrtPolicy

Sqrt operator (Sqrt(a)) policy. The supported values are DEFAULT, QUIET, NULLING, and `SIGNALLING. The default value is QUIET.

OperatorPowPolicy

Power operator(pow(a, b); power(a, b)) policy. The supported values are DEFAULT, QUIET, NULLING, and SIGNALLING. The default value is QUIET.

Optimizer cost constants

The cost variables described in this section are measured on an arbitrary scale. Only their relative values matter, hence scaling them all up or down by the same factor will result in no change in the optimizer choices. By default, these cost variables are based on the cost of sequential row groups fetches; that is, OptimizerSeqRowGroupsCost is conventionally set to 1.0 and the other cost variables are set with reference to that. But you can use a different scale if you prefer, such as actual execution times in milliseconds on a particular machine.

Unfortunately, there is no well-defined method for determining ideal values for the cost variables. They are best treated as averages over the entire mix of queries that a particular installation will receive. This means that changing them on the basis of just a few experiments is very risky.
OptimizerSeqRowGroupsCost

Sets the optimizer’s estimate of the cost of a table row group fetch that is part of a series of sequential fetches. The default value is 1.0.

OptimizerCpuOperatorCost

Sets the optimizer’s estimate of the cost of processing each operator or function executed during a query. The default value is 0.0025.

OptimizerCpuTupleCost

Sets the optimizer’s estimate of the cost of processing each row during a query. The default is 0.01.

Other optimizer options

OptimizerConstraintExclusion

Controls the query optimizer’s use of table constraints to optimize queries. By default, it is set to TRUE.

When this parameter allows it for a particular table, the optimizer compares query conditions with the table CHECK constraints, and omits scanning tables for which the conditions contradict the constraints.

Also checking for self-contradictory query conditions is performed.

For example:

CREATE TABLE tbl (a bool, ...);
...
SELECT * FROM tbl WHERE a AND not a;

Here, the a AND not a expression is self-contradictory and will fail the WHERE condition for each row of the tbl table. With constraint exclusion enabled, this SELECT will not scan tbl at all thus improving performance.

Turning this option on could impose extra planning overhead that could be quite noticeable even on simple queries. If you have problems with it you might prefer turning the option off entirely.
OrderbyWithLimitOptimization

Enables and disables optimization of queries with the ORDER BY..LIMIT:

SELECT * FROM t1 ORDER BY <field list> LIMIT n [OFFSET m]

The default value is TRUE.

While the default algorithm performs sorting of the whole dataset first, involving using on-disc cache for data parts, the optimized algorithm performs the in-memory operations which involve using memory enough for storing LIMIT+OFFSET rows only, without on-disc cache. This significantly improves the algorithm speed, even in comparison with algorithm in cases when no disc cache used.

The behavior of this optimization is also defined by the SortMemoryLimit parameter. For the OFFSET+LIMIT sum, there may be insufficient memory to perform the ORDER BY operation. If the memory limit is reached, the optimization falls back to the default algorithm. To avoid this, try to increase the value of the SortMemoryLimit parameter.

Parser settings

BackslashEscaping

Configures the backslash (C-style) escape using in string constants and delimited identifiers. By default, it is set to TRUE.

For syntax details, see the Backslash (C-style) escaping section.

Settable configuration settings

Several parameters can be specified via the SET command. The changes work only for the current session (connection) and are invisible for other users. Currently, only Conversion settings, and FloatPrecision settings are supported.

Configuring via command line

The -c(--config) command line option lets you specify custom config file location.

The -p(--parameter) lets you specify any config parameter manually in command line. For example:

raijin-server -p GlobalLogLevel=WARNING -p Port=2501

starts the server on port 2501 and logs only messages with severity >= WARNING.