QDB Command Line

Configure and maintain QDB databases

Synopsis:

qdb [-A] [-c config_path] [-C policy] [-D] [-I test] [-n mountpoint]
    [-N control] [-o option[,option2...]] [-P permissions] 
    [-r mode] [-R mode] [-s [data@]routine] [-t timeout] [-T timeout] 
    [-u user_group_str] [-v[v...]] [-V] [-W time] [-X path]

Options:

-A
Turn off exclusive mode to allow other applications to use the database files.
-c config_path
Specify an overridden PPS configuration path. See the “PPS configuration path” section for more information.
-C policy
Specify a database connection sharing policy. The policy argument can be one of:
  • unique
  • private
  • reuse
  • share
See the “Sharing connections between clients” section for more information.
-D
Disable the shared cache. You should use this option only if you need to debug shared caching.
-I test
Perform a database integrity test at loading time. The test argument can be one of:
  • none
  • basic
  • partial
  • full
See the “Database integrity testing” section for more information.
-n mountpoint
QDB resource manager mountpoint. The default is /dev/qdb.
-N control
Name of the database control entry. The default is .control.
-o option1 [,option2...]
Configure miscellaneous options. The options are:
  • unblock=0 | 1 — set whether or not to install an unblock handler (i.e., to allow a signal to interrupt an SQL operation).
  • threadmax — set the maximum number of threads to allocate; the default is 64.
  • threadhi — set the maximum number of threads that can be kept in a blocked state but ready to work.
  • threadlo — set the minimum number of threads to keep blocked but ready to work.
  • rwbias=r|w — set preferential access for readers (with 'r') or writers (with 'w') when multiple threads are contending for a database lock. By default, no preferential access is granted; you can override this setting to improve performance.
  • tempstore=directory — set the directory name where qdb places certain temporary files. You can set this to a RAM disk location to prevent excessive disk access.
  • bkcopy=buffer_size — set the size of the buffer to use when making a backup or compressing. The default value is 64 KB and is probably acceptable for most cases.
  • trace — log SQL statements before qdb executes them. You must set verbosity (-v) to level six for this feature to work.
  • profile — log SQL statements and the time it took to execute them, after qdb finishes executing them. You can additionally specify the -W time option to log only SQL statements that take longer than the time specified in milliseconds. You must set verbosity (-v) to level six for this feature to work.

  • verchk=none|major|minor|revision|strict — check the compatibility between the SQLite version of the QDB server and that of the installed SQLite library.

    The default value is strict, which means the exact revision, including any patches, must match between QDB and the library. For example, if you're running a QDB server built from version 3.7.11-patch17 but your installed SQLite library is of version 3.7.11 (but with no patch), the version check fails and QDB doesn't start.

    By relaxing the strictness of the version checking, you can use a SQLite library with a version different from the one that QDB was built from.

-P permissions
Define access permissions for the database and backup files. By default this is 0664.
-r mode
Set the connection recovery mode. This mode determines what happens when a database problem is discovered and corrected. The argument can be one of:
  • manual — clients receive ESTALE errors until they disconnect and reconnect.
  • auto — clients are automatically reconnected, and receive no notification that a problem was detected and repaired.
-R mode
Set the database creation and recovery mode. The mode argument can be one of:
  • manual
  • auto
  • set
See the “Database recovery” section for more information.
-s [data@]routine
Change the configuration of a user-defined collation sequence. All collation setup functions expect data in the same format as you would specify it through qdb_collation(). For example, -s en_US@cldr would name the cldr collation routine and invoke its setup function at startup, passing in the en_US string.
Note that the data portion of the argument is optional; specifying a -s argument without data lets you set the configuration of a collation to its default setting.
To configure multiple collations, use multiple -s options. All registered collations, which are listed in the Collation option in the database configuration object, have their setup functions invoked at startup so they may initialize themselves, even if they're not named in -s options. However, to pass nondefault data to a collation setup function, you must use this option and provide the data in the argument value.
-t timeout [ block | nonblock ]
Set the busy-wait timeout on database accesses made with qdb_connect(), in milliseconds. By default, this is 5000 milliseconds. See the “Busy timeout” section for more information.
-T timeout [ block | nonblock ]
Set the busy-wait timeout on implicit database connections (i.e., those made without a client context), in milliseconds. By default, this is 5000 milliseconds. See the “Busy timeout” section for more information.
-u user_group_str
Change the process permissions after the initial setup so qdb runs with the specified user and group. The string value for this argument can be in one of the two forms explained in set_ids_from_arg() in the C Library Reference.
-v
Increase output verbosity. The more -v options you specify, the more verbose the output. You can specify up to seven -v levels. Messages are written to the slog2info log.
-V
Replicate output messages to the console and the slog2info log.
-W time
Used with the -o profile option to log only those SQL statements that take longer than time (which is specified in milliseconds). The default for time is 5000 milliseconds.
-X path
Set a script to run when qdb encounters a corrupt database. For further details, see “Handling corrupt databases”.

Description:

The qdb utility lets you set the properties of a database connection on the command line. You can override default paths to the configuration object or the device file, set the creation and recovery modes, and configure options such as the number of threads used by qdb.

The -v option causes qdb to output the results of database operations to the system log readable with slog2info; this verbose mode is useful for troubleshooting your setup and database usage. You can use the verbose option with the trace and profile settings under the -o option to log the results of SQL statement execution.