Database Options

Database options and database process options control the activity of database processes. Options specified on the database will be applied to all processes started for that database while database process options apply to Transaction Engine (TE) and Storage Manager (SM) database processes only. All options take effect at process start time for a TE or SM.

The following table provides information for database options. For each option, the table below lists the following:

Option Name

These are case sensitive.

Option Argument

Either a list of possible values in curly brackets or an indication of the type of argument expected (such as file, directory or milliseconds).

Default Argument

Where a default exists, may be empty.

Description

Details the behavior controlled by the option.

Restrictions

Some options can only be applied at the database level when the database is created. These will be used when any processes are started for the database. Some options apply to only certain database processes, for example, the journal-max-directory-entries option applies to SMs but not TEs. These are called database process options. Some options can be specified at the database level or specified as a database process option when the process is started.

This distinction is listed in the restrictions column in the table below as one of the following:

  • Database for a database option

  • TE for a database process option that applies to TEs

  • SM for a database process option that applies to SMs

    If no restrictions are specified for an option, then it can be used as both database option and database process option.

Available Options

Option Name Option Argument Default Argument Description Restrictions

archive-threads

n

1

Number of parallel archive write threads. Increasing the value is recommended when using high latency storage, which is typical with Cloud storage or a Storage Area Network (SAN).

SM

async-sm-delay-gc-timeout

seconds

600 (10 minutes)

Amount of time that an Asynchronous SM may delay record version garbage collection to prevent discarding the last consistent state. If this time is exceeded, the Asynchronous SM will log a message and shutdown.

ASM

cipher-suites

{TLS|LEGACY-SRP|TLS,LEGACY-SRP}

TLS,LEGACY-SRP

Specifies accepted encryption protocols available for all connections to engines, administration processes and SQL clients. Protocol preference, is defined by the order in which they are listed as comma-separated values. For more information on encryption protocols, see Network Encryption.

commit

{safe|local|remote[:n]|region[:n]}

safe

Commit mode

Database

config

config_file

None

Specifies a configuration file to be passed to the TE, SM process. The configuration file can contain any of the options in this table, represented as key/value pairs, where each key is separated from its value with whitespace, and each key/value pair resides on its own line in the file. This configuration file will be passed to all processes (TEs, SMs) in the database. If the configuration file contains any options that might refer to a local directory path, this path must exist on all database hosts.

crash-dir

directory

$NUODB_LOGDIR/crash

Specifies a directory in which to place crash reports for NuoDB processes (TEs, SMs). This option is for Linux only. $NUODB_LOGDIR for package installations is /var/log/nuodb and for Tar/Local installations is $NUODB_HOME/var/log.

disable-stats-collection

None

None

Disables automatic collection of statistics for indexes, which is enabled by default. If automatic statistic collection is disabled, it is necessary to manually re-calculate index statistics using the ANALYZE command on every table. For more information, see ANALYZE.

enable-query-termination

None

None

Allows TEs to terminate user queries in order to relieve memory pressure. For more information, see SQL Query Termination.

enabled-ciphers

Comma-separated list of cipher names

AES-256-CTR,RC4

A list of acceptable ciphers for clients to connect to the database with. The first cipher is the most preferred. Cipher names are case-sensitive and must be entered exactly as shown. The client will supply a list if ciphers it accepts: if no overlap is found the connection will be refused. The full list of available ciphers are: AES-256-CTR, RC4, and None.

hot-copy-threads

n

5

Number of threads used when copying atoms during a hot copy operation. For more information on performing hot copy operations, see Backing Up and Restoring Databases.

SM

io-warn-time

milliseconds

10000
(10 seconds)

A message is logged when a disk I/O operation takes longer than the value specified for this option. These log message are prepended with "Slow I/O:…​".

io-fatal-time

milliseconds

3600000
(1 hour)

A message is logged, and the process is killed, when a disk I/O operation takes longer than the value specified for this option. This avoids a scenario where the entire database hangs because one disk is not responding.

journal-hotcopy

{enable|disable}

disable

Enable journal hot copy on the current SM.
For more information, see Using Journal Hot Copy.

SM

journal-max-directory-entries

n

1000

Sets the maximum number of journal files in a journal sub-directory. A new journal sub-directory is created when the specified limit has been reached.

SM

journal-max-file-size-bytes

n

4000000

Specifies the maximum size in bytes of a journal file. However, the journal may write a file larger than the maximum file size if a single compressed journal message is larger than the specified maximum. The journal messages will be appended to the same journal file until the maximum file size is reached.

SM

journal-single-file

{enable|disable}

disable

Enables or disables the starting of a new journal file for every sync.

SM

journal-sync-method

{kernel|disk|osync}

disk

Specifies the file system synchronization mechanism when the journal needs to ensure the durability of a commit. The synchronization mechanism has been specifically tuned for each supported OS.

  • The kernel synchronization method is the fastest but requires a battery backed disk controller. The kernel method on Linux also requires the file system to support fallocate, that is, ext4.

  • The disk synchronization method is the most durable but slowest method.

  • The osync method is available for copy-on-write files systems, also known as ZFS.
    For additional information, see Tuning Tips for Journal Performance.

SM

jvm-lib

path

If a value is set for jvm-lib, that location is searched first. If jvm-lib is not set, or a JVM is not found in that location, then JAVA_HOME is searched. If JAVA_HOME is not set or a JVM is not found, then:

On Linux: standard paths are searched.

On Windows: the Windows registry is checked and then common paths are checked.

TE

ldap-base

ldapBase

Required for LDAP authentication. Starting point for the LDAP search instead of the default

Example:

ldap-dn 'ou=people,dc=example,dc=com'

TE

ldap-ca

ldapCA

Optional. LDAP certificate authority certificate to validate server certificate for ldaps. (Linux only)

TE

ldap-conf

ldapConf

Optional. LDAP path to ldap.conf file too use (see man ldap.conf) (Linux only)

TE

ldap-dn

ldapDN

Required for LDAP authentication. This, in conjunction with ldap-pass, allows proxy level authentication and the specified account must have search privileges on the ldap-base. It is used to search for the full Distinguished Name (DN) of the user that connects.

Example:

ldap-dn 'cn=manager, ou=people, dc=example, dc=com

TE

ldap-lib

ldapLib

Optional. LDAP openldap library name (Linux only)

TE

ldap-pass

ldapPassword

Required for LDAP authentication. This, in conjunction with ldap-dn, allows proxy level authentication and the specified account must have search privileges on the ldap-base. It is used to search for the full Distinguished Name (DN) of the user that connects.

TE

ldap-type

{unix|windows}

Required for LDAP authentication. LDAP server type. Only unix or windows is allowed.

TE

ldap-uri

ldapURI

Required for LDAP authentication. Specify URI referring to

Example:

'ldap://localhost:389'

the LDAP server(s).

TE

lsa-file-max-waste

n

10

Maximum allowed wasted space in one LSA-file before it becomes a candidate for compaction, as a percentage.

SM

lsa-file-size

n

2097152 (2 MB)

Target size of an LSA-file, in bytes.

SM

lsa-max-map-waste

n

75

Maximum allowed wasted space in a catalog’s LSA-map-files before they become candidates for compaction, as a percentage.

SM

lsa-waste-compaction-start

n

30

Percentage of wasted disk space in Log-Structured Archive (LSA) to trigger the compaction process.

SM

lsa-waste-compaction-stop

n

20

Percentage of wasted disk space in LSA to stop the compaction process.

SM

max-client-connections

n

0

The number of concurrent client connections a TE will accept.

When starting a TE, use this property to set a specific number of client connections. For more information, see Setting Client Connection Limits for Transaction Engines.

The default (0) allows the TE to accept as many connections as are allowed by the operating system (that is, the same number of sockets that the process can open), minus some reserved for database operations. If the TE cannot accept the number of connections requested (because the operating system does not allow that many open sockets), the TE does not start.

Connections are not created until needed by a client, regardless of this setting. NuoDB only checks the max-client-connections value against the operating system’s largest allowed value.

Setting a non-zero value for this startup parameter results in the TE refusing new client connections if the number of current open connections is equal to the value.

TE

max-full-gc-skips

n

100

Specifies the number of normal garbage collection cycles to every full garbage collection cycle (which is every 1000 seconds). By default, there are 100 normal garbage collection cycles to every full garbage collection cycle. For information on generating index statistics, see ANALYZE.

max-http-connections

n

16

Maximum number of concurrent HTTP requests permitted towards the same server. This option is useful when you want to the limit the number of current connections between the SM and the archive. This option can be used only with HDFS and Amazon S3.

TE

max-lost-archives

n

0

The number of leader candidates that may be permanently lost (crash and become non-restartable) at a time before durability is compromised. For a database to be available to commit update transactions, max-lost-archives + 1 leader candidates must be running in the system. The default is 0, meaning that the system is resilient to any number of ordinary failures and available for updates as long as at least one leader candidate is running; but, if 1 or more leader candidates is permanently lost then durability may be compromised.

When max-lost-archives > 0, the transaction can fail to commit, and then roll back. But if the whole database fails before the transaction completes roll back, the partially rolled back transaction can be dredged as pre-committed and promoted to committed, thus creating a torn transaction.

mem

n[K|M|G][i]

2Gi

Sets the maximum amount of memory to be utilized by a database process (in bytes). To specify the amount in kilo-, mega-, giga-, kibi-, mebi-, or gibibytes, suffix the amount with K, M, G, Ki, Mi, or Gi (respectively).

node-port

[n[,n]]

NuoDB decides

Port to use for this host, or optionally, a range of port values. By default NuoDB determines the port to be used.

optimizer-version

v2,v3

v3

Configures the default optimizer for the connections serviced by the TE. This value can be overridden using the queryoptimizer connection property.

Optimizer v2 was deprecated in NuoDB 6.0.

TE

peer-ciphers

Comma-separated list of cipher names

AES-256-CTR,RC4

A list of acceptable ciphers for peers to connect to the database with. This includes other SMs or TEs as well as connections to the admin services. The first cipher is the most preferred. Cipher names are case-sensitive and must be entered exactly as shown. The client will supply a list if ciphers it accepts: if no overlap is found the connection is refused. The full list of available ciphers are: AES-256-CTR, RC4, and None.

ping-timeout

n

Not set

Normally, processes in the database (TEs, SMs) ping other processes at regular intervals and wait for a response. When network communication with a process times out, the process is evicted from the database by its peers.
Failure detection can be enabled by setting the ping-timeout option, specified in seconds. NuoDB recommends an interval timeout of 60 seconds or greater.
A setting of 0 means wait forever. That is, there is no time out.

Database

remote-syslog

log-options (see below)

None

Equivalent to the syslog option but for use with the remote-syslog-server option.

remote-syslog-server

hostname:port

Not set

Send all logging information to the server at the specified remote host and port number. If not specified, the port number defaults to 514.

scratch-dir

directory

N/A

Specifies a directory that NuoDB can use for temporary files to facilitate the processing of memory intensive operations.

For SMs, the default value for --scratch-dir is {archive_dir}/nuodbtemp. For TEs, there is no default value.

Database

scratch-dir-max-size

n[K|M|G][i]

0

Sets the maximum size of the scratch-dir (in bytes). To specify the amount in kilo-, mega-, giga-, kibi-, mebi-, or gibibytes, suffix the amount with K, M, G, Ki, Mi, or Gi (respectively).

0 (the default) means that no maximum size of the scratch-dir is enforced by NuoDB.

stats-collection-threshold

n

10000000000

If any table reaches this cardinality (number of rows), index statistics will cease to be collected automatically for it. Statistics may still be collected manually by issuing the ANALYZE command on the table or any of its indexes. If ANALYZE is issued on the table itself while it is below this cardinality, automatic collection will resume. For more information, see Running ANALYZE to Obtain Index Statistics.

sql-client-tcp-keepalive

tcpKeepalive

Not set

Enable and configure TCP keepalive on incoming SQL client connections. Format tcpKeepalive TCP_KEEPIDLE:TCP_KEEPCNT:TCP_KEEPINTVL. Example: '60:6:10'.

storage-group-observer

storage group names

None

A comma-separated list of storage group names that the Asynchronous SM observes, but does not lead. This is controlled by the --passive and --observes options of the nuocmd archive subcommands.

ASM

syslog

log-options (see below)

Send logging information to the system log (only if TE or SM is running on a Unix host).

verbose

log-options (see below)

None

Report logging and other information. This information is captured in the nuoadmin.conf log file.

Logging Options

To use the remote-syslog, syslog or verbose options, you must specify at least one logging level and/or logging category to log.

For details refer to Logging Options.