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 routine]
        [-t timeout] [-T timeout] [-v[v...]V] [-W time] [-X path]

Options:

-A
Turn off exclusive mode: allow other applications to use the database files.
-cconfig_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 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 can be one of:
  • none
  • basic
  • partial
  • full

See the "Database integrity testing" section for more information.

-n mountpoint
The QDB resource manager mountpoint. By default this is /dev/qdb.
-N control
Name of the database control entry. By default this is .control.
-o option
Configure miscellaneous options. The options are:
  • unblock=0 | 1 — set whether or not to install an unblock handler (that is, to allow a signal to interrupt an SQL operation).
  • threadmax — set the maximum number of threads to allocate to qdb; the default is 64.
  • threadhi — set the maximum number of threads that can be kept in a blocked state ready to work.
  • threadlo — set the minimum number of threads to be kept in a blocked state ready for 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 tmpfs 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 six for this feature to work.
  • profile — log SQL statements after qdb executes them, as well as the time it took to execute them. You can additionally specify the -Wtime option to log only SQL statements that take more than the specified time, in milliseconds. You must set verbosity (-v) to six for this feature to work.
  • verchk=none | major | minor | revision | strict — check the compatability of the SQLite version QDB was built for versus that of the installed SQLite library.

    The default value is strict, which means the exact revision, including any patches, must match between two the SQLite versions. For example, if you're running a QDB service built for version 3.7.11-patch17 but your installed SQLite library is of version 3.7.11 (but 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 what QDB was built for.

See also thread_pool_create() in the Neutrino Library reference

-P permissions
Access permissions for the database and backup files. By default this is 0664.
-R mode
Set the database creation and recovery mode. The mode can be one of:
  • manual
  • auto
  • set

See the "Database recovery" section for more information.

-r mode
Set the connection recovery mode. The mode specifies what happens when a database problem is discovered and corrected. It 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.
-s routine[@data]
Name special collation routines and data. This setting specifies a name (or wildcard pattern) of collation functions that expect the format of data that you will pass in via qdb_collation(). Only those registered collation functions that match this pattern will get their setup function invoked (since the format of the data must be known to the function). By default, all functions have their startup functions invoked.

You can also use the -s option to set the initial setup data. For example, -s cldr@en_US would set the magic function name to "cldr", and also invoke the setup function with the "en_US" string at startup.

-t timeout | block | nonblock
Set the busy-wait timeout on database access, 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 database connection, in milliseconds. By default, this is 5000 milliseconds. See the "Busy timeout" section for more information.
-v
Increase output verbosity. The more -v options you specify, the more verbose the output. Messages are written to the sloginfo log.
-V
Replicate output messages to the console, as well as to the sloginfo log.
-W time
Used in conjunction with the -o profile option: log only SQL statements that take longer than time (specified in milliseconds). The default for time is 5000 milliseconds.
-X path
Set a script to run when qdb encounters a corrupt database. See "Handling corrupt databases".

Description:

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

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