![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
qdb [-A] [-c config_file] [-C policy] [-D]
[-I test] [-n mountpoint] [-N control] [-o option[,option2...]]
[-P permissions] [-R mode]
[-r mode] [-s routine]
[-t timeout] [-T timeout] [-vV] [-W time] [-X path]
See the “Sharing connections between clients” section below for more information.
See the “Database integrity testing” section below for more information.
See the “Database recovery” section below for more information.
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.
The QDB database directory can be on any QNX or POSIX filesystem with read/write access (including memory-based filesystems, such as tmp-fs). QDB can run from QNX filesystems visible via Qnet, but can not run from a CIFS or NFS filesystem.
A schema file contains all the SQL commands to create the database schema the way you want. Here's an example:
CREATE TABLE customers( customerid INTEGER PRIMARY KEY AUTOINCREMENT, firstname TEXT, lastname TEXT );
Save that content in /db/customerdb.sql.
If you have any database schema files (for example, /db/customerdb.sql), you need to add them to the QDB configuration file before starting the QDB server. For information on specifying schema files and other database configuration settings, see “The configuration file” below.
The QDB server must be run as root. For debugging purposes, you should start qdb with -v options to get verbose output. The v option is cumulative, with each additional v adding a level of verbosity, up to 7 levels. The -V option sends output to the console and to sloginfo.
Once QDB is running, you can check that it sees your databases by running ls /dev/qdb/. Using the example of a database named customerdb, we should see a file called /dev/qdb/customerdb.
The filesystem that QDB uses for temporary storage must support POSIX file locking. File locking is required for database vacuuming.
The QDB checks its temporary storage as follows:
If all the above conditions are met, the QDB sets the internal temporary storage to the location specified by the tempstore option. If any of the above conditions are not met, the QDB logs errors to the slog and fails to start up.
If all the above conditions are met, the QDB sets the internal temporary storage to the value of TMPDIR. If any of the above conditions are not met, the QDB logs errors to the slog and fails to start up.
You can create a list of databases that you'd like to be combined as if they formed a single database. This is called auto-attaching a database. This is useful for breaking up a database into separate pieces for performance reasons (each piece gets its own lock, which makes multi-user access more responsive). It's also useful for moving parts of a database to different storage mediums (such as a RAM filesystem).
The list of databases is read from a configuration file, specified by the Auto Attach= option. For more information, see “The configuration file” below.
When using the Auto Attach parameter to attach more than one database to another database (attaching multiple sections to one section) you must make sure that the order in which the sections are listed in the configuration file are the same as the order in which they are listed via the Auto Attach parameters. The examples below show incorrect and correct lists. To simplify the examples, only the section headings are shown; parameters are not shown.
Note that the section definition order does not match the attach order.
[mme_library] [mme_temp] [mme_custom] [mme] Auto Attach = mme_library Auto Attach = mme_custom Auto Attach = mme_temp
Note that the section definition order matches the attach order.
[mme_library] [mme_custom] [mme_temp] [mme] Auto Attach = mme_library Auto Attach = mme_custom Auto Attach = mme_temp
Note that the attach order matches the section definition order.
[mme_library] [mme_temp] [mme_custom] [mme] Auto Attach = mme_library Auto Attach = mme_temp Auto Attach = mme_custom
At startup, QDB tests the integrity of databases, according the -I option specified. It will execute statements based on this option, as follows:
 |
The more verification the QDB performs at startup, the greater the time needed for startup. For production environments, you will need to find the optimal balance between the amount of verification required and the time needed to start the QDB. |
You can execute SQL statements on your QDB databases from the command-line using the qdbc utility. See qdbc for more information.
QDB is configured with a single file, which is specified with the -c command-line option. If this file is in the same location as the database SQL files (by default, /db/), you can use relative paths in the configuration file to point to schema files and database locations. Otherwise, you need to use absolute paths.
The configuration file is composed of lines of text. Blank lines are ignored, as is any leading or trailing white space. Lines beginning with a number character (#) are comments. The configuration file consists of named sections, each of which configures the database named in the enclosing square brackets ([ ]) that begin the section. Suppose you have a database named customerdb. You would then write a section beginning with [customerdb] to identify the settings that QDB should apply to that database.
Following each section header are parameter lines in the form key=value. Parameters apply to the current section. The Filename parameter, which names the database storage file, is mandatory but all other parameters are optional. A basic configuration for the customerdb database would look like:
[customerdb] Filename=/db/customerdb Schema File=/db/customerdb.sql
Each section (and database) name is presented in /dev/qdb. Clients use that same name to establish a connection. The database is then configured using the following parameters:
An initial schema is optional; without an initial schema, a new database will just be empty.
Attached databases are a convenience to provide access to tables that are physically stored in a different database file. Facilities exist in QDB to also include attached databases in other maintenance operations, such as backup or vacuum.
See also “Auto-attaching databases” above.
This directory must exist at startup (though it does not need to contain a valid backup); otherwise qdb exits with an appropriate error. If any existing backup files are located in these directories, they are sorted by date and overwritten oldest-to-newest when performing backup operations, and used in newest-to-oldest order to restore a missing or corrupt database.
QDB checks for the existence of the library and the specified symbol at startup, and exits with an appropriate error if they're not found.
Here's a sample configuration:
[db]
Vacuum Attached = TRUE
Auto Attach = db1
Vacuum Attached = FALSE
Auto Attach = db2
In this example, a qdb_vacuum() operation on db will also vacuum db1 but not db2.
You can use the Backup Attached=TRUE setting to provide a facility similar to the old *.bks files. For more details on the scope of maintenance operations with respect to attached databases, refer to qdb_vacuum(), qdb_backup(), and qdb_getdbsize().
To create RAM-based databases, point the Filename= option to the RAM-disk file.
You can also create temporary databases by defining a database with a Filename=:memory: entry. This action creates a private, temporary, in-memory database, visible only in the scope of the database connection. Each connection to such a database has its own temporary file, which is removed when the connection is closed.
For example, you could specify Backup Via=/dev/shmem. When backing up, QDB locks the database, copies it to /dev/shmem, and then releases the lock. Then, in a second step, qdb performs the copy and compress operation into the location specified by Backup Dir=, without needing to lock the database.
You can allow multiple clients to share a database connection. This is controlled by the -C option. These modes are:
Connection sharing exists because a non-negligable amount of work must be done to establish a database connection (QDB must allocate memory, access files, attach databases and callback functions, configure connection parameters, and so on), and if clients do not assume any state, then this processing work can be avoided. The QDB server detects if connection parameters have been changed by a client, and restores them when the connection moves in or out of the pool in unique, reuse or share modes.
This connection sharing should be safe (unless the client destructively modifies the environment via SQL, such as by executing a DETACH DATABASE statement). However, for full backwards compatibility, connection sharing can be overridden on each qdb_connect() call, and the default libqdb access mode is private.
If a client is leaving open transactions across multiple calls to qdb_statement(), then it needs a dedicated connection (private or reuse or should not set the QDB_CONN_DFLT_SHARE flag).
The default startup mode for QDB is with both shared caching and exclusive modes enabled:
|
QDB will exit immediately if it is started with shared cache disabled and exclusive mode enabled. For example:
# qdb -c /db/qdb.cfg -v -D -Otempstore=/fs/tmpfs -Rset qdb: Exclusive locking mode requires that shared cache be enabled |
Shared caching can both improve performance times and reduce the total amount of memory cache required for multiple connections. Shared caching also reduces the total amount of memory required for multiple database connections, because multiple connections can share the same memory cache.
For example, without shared caching, if 1 MB of memory is required for each database connection, 40 connections require 40 MB of memory. However, with shared cache enabled, these 40 connections can share the same memory cache, allowing you to reduce the memory cache to 25 MB (or another size determined by your environment and performance requirements). Further, with shared cache, there is no duplication in memory, so in the 25 MB of memory you may have almost the entire database, virtually eliminating the need for disk I/O.
The -R option controls the recovery actions QDB performs when it encounters a missing or corrupt database file. The options are:
A corrupt or missing database file is restored from the most recent, valid backup that can be located. If there is no such backup, then a blank database is recreated from the original schema definition.
The set master is the database that attaches other databases (by using the Auto Attach option in the configuration file). The backup set contains the set master and all attached databases that have Backup Attached enabled. The set master can be backed up incrementally and still belong to the set.
|
QNX recommends the following in order to back up and restore your databases as a coherent set:
|
The two timeout settings are differentiated as follows:
A value of block is equivalent to an infinite timeout period, and nonblock is equivalent to a timeout period of 0.
The -X lets you provide qdb with a program or script to run when it encounters a corrupt database. If the program or script appears to run correctly, qdb will continue. The program or script is responsible for stopping and starting qdb if a start of stop is necessary.
Below is a sample qdb startup command with the -X:
# qdb -c /etc/qdb.cfg -X /usr/bin/recover_db.sh
Below is a sample script that can be launched by qdb when it encounters a corrupt database:
recover_db.sh: #!/bin/sh # # This script will kill qdb and mme, # remove the database files # on disk, and restart qdb and mme. slay qdb mme-generic rm -f /fs/tmpfs/* rm -f /mnt/qdb_backup/* # Call an external program # to launch qdb and the MME. # /usr/bin/mme-launch # EOF
|
|
You can write some maintenance commands to the /dev/qdb/.control entry (and read back the result). The current commands supported are (where DBNAME is the name of the database):
|
|
|
|