Database configuration objects

QDB databases are managed with configuration objects, each of which configures one database. The configuration objects are text files that specify the paths to the database schema and storage files as well as policy settings such as backups.

The files are named after the databases that they configure. For example, suppose you have two media content databases named hdd and cdrom. You would then create two configuration objects named hdd and cdrom. For an overview of all database-related files, see Summary of database files.

By using a separate SQLite storage file for each database, QDB allows you to dynamically load and unload individual databases so you can keep in memory only the data needed for the active client application.

Note:
QDB doesn't support on-the-fly configuration changes after a database is loaded. To modify the configuration, you must unload the database, update its configuration object, and reload the database. You must also ensure that the changes are compatible with the previous configuration.

Configuration object contents

The database configuration object gets parsed by QDB to set up the database. Lines specifying parameters are in the form key::value. Unknown parameter types are ignored and so they can be made into comments, but you must still use the :: delimiter on the comment line. For example, you can enter MyComment:: on a line and QDB will treat it as an unsupported parameter and ignore that line. For an example of a database configuration, see Sample configuration object.

The configuration object must contain this parameter:
Filename
The name of the database storage file, which is the raw SQLite file. It must have an absolute path but it can refer to any file location. At database loading time, either this file or its parent directory must exist; otherwise, the loading attempt fails and QDB sets the status to Error. If the database file doesn't exist but its parent directory does, the file is restored from the newest valid backup (if possible) or a blank database file is created.
All other database configuration parameters are optional. You can define these parameters:
AutoAttach
A comma-separated list of other databases to attach to the current one (using the SQL ATTACH DATABASE statement) whenever a database connection is established.
Attached databases are a convenience to provide access to tables that are physically stored in different database files. 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 transfering parts of a database to different storage medias such as RAM filesystems.
QDB allows you to include attached databases in other maintenance operations, such as backup or vacuum.
Note:
If any attached database is unavailable at loading time, QDB sets the current database's status to AttachWait and makes the database inaccessible.
BackupAttached, SizeAttached, VacuumAttached
These entries control what maintenance operations should apply to attached databases when a command is issued to the main database. Each parameter lists the attached databases affected by the operation.
Suppose you have a main database named mp3_tunes_0 with two attached databases named mp3_tunes_1 and mp3_tunes_2 and you define these paramaters: 
AutoAttach::mp3_tunes_1,mp3_tunes_2
VacuumAttached::mp3_tunes_1
In this case, a qdb_vacuum() operation on mp3_tunes_0 will also vacuum mp3_tunes_1 but not mp3_tunes_2.
Note:
Any database named in an operation-based attachment parameter such as VacuumAttached must also be named in AutoAttach, or that database won't be processed during the operation.
For more details on the scope of maintenance operations for attached databases, refer to qdb_backup(), qdb_getdbsize(), and qdb_vacuum().
BackupDir
A comma-separated list of directories that store database backups. When you specify multiple directories, they're used in rotation to store the backup files. This feature ensures that should a backup be interrupted or aborted by a power failure, another older backup is still available.
These directories must exist at loading time (though they don't need to contain valid backups); otherwise, the loading attempt fails and QDB sets the database status to 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 when restoring a missing or corrupt database.
BackupVia
An interim directory that the database is copied into as part of the backup. To ensure the backup is consistent, QDB puts a read lock on the database while copying and compressing it, so the database may be locked a long time if the destination is slow (e.g., flash).
Suppose you specify: 
BackupVia::/dev/shmem
When backing up, QDB locks the database, copies it to /dev/shmem, and releases the lock. Then, in a second step, QDB copies and compresses the database into the location specified by BackupDir, without needing to lock the database.
ClientSchemaFile
The name of the file (with an absolute path) that contains the SQL commands to execute every time a client calls qdb_connect().
Use this feature for changing database settings that can't be premanently modified. An example would be the PRAGMA commands, which modify non-table data such as journaling mode or case-sensitive-like status. Don't use client schema files to do regular database work because doing so slows down new connections.
You can also use this mechanism to implement cross-database triggers.
Collation, Function
These entries install user-provided collation (sorting) routines and scalar/aggregate functions. The argument format is a comma-separated list of library symbols in the form tag@library.so, where tag is the symbol name of the function description structure and library.so is the name of the shared library containing the code.
Unlike the paths to other key files, the library paths can be relative or absolute. Relative paths are looked up in the library search directories (refer to dlopen() in the QNX Neutrino C Library Reference for more details).
In this release, you can install multiple collation functions as well as multiple scalar functions per database. You can also specify symbols from as many shared libraries as you want. For example, you could write: 
Collation::UTF-8_Sort@libsort.so,UTF-16_Sort@libsort.so
Function::sampleData@libstats.so,implToMtrc@libunits.so
For information about the function description structures and the setup and sorting functions that you must define, see the Writing User-Defined Functions chapter.
QDB checks for the existence of the libraries and the specified symbols at loading time. If any are not found, the loading attempt fails and QDB sets the database status to Error.
Compression
The compression algorithm to apply to backups. The supported options are:
  • none (for no compression, which is the default)
  • lzo (for LZO compression)
  • bzip (for BZIP2 compression)
  • diocopy (for direct I/O copy)
The lzo compression algorithm is the fastest but the bzip algorithm offers the highest compression. Direct I/O doesn't perform any compression; instead, QDB uses the fileset utility to copy the database using direct memory access (DMA). Direct I/O is a fast way to back up data if the persistent storage supports DMA.
The compressed files are named by adding the appropriate extensions to the original database filenames. By default, backup files aren't compressed.
CompressionVia
This entry is used with the BackupVia entry and any Compression setting specified for the backup. By default, the BackupVia feature first makes a raw/uncompressed copy of the database in the temporary directory and then performs the compression. This works if you have enough space and it read-locks the database for the least amount of time, but you can use less space (at the expense of more time) by compressing during the copy. This option is false by default; if you set it to true, the compression is done in the first step.
DataSchemaFile
The name of the file (with an absolute path) that creates the initial data in the database. This text file contains the SQL commands to populate the database when it is created.
This option is processed only if the SchemaFile option is set.
SchemaFile
The name of the file (with an absolute path) that contains the SQL commands to create the initial schema of tables, indexes, and views for the database. The schema file is used only to set up the database if it didn't already exist.
An initial schema is optional; without an initial schema, a new database will be empty.

Sample configuration object

This basic database configuration names the files for storing the database, defining the schema, and populating the database with initial data: 
Filename::/root/tmp/cdrom0_db
SchemaFile::/etc/mm/sql/mmsync.sql
DataSchemaFile::/etc/mm/sql/mmsync_data.sql

You would give the configuration object the same name as the database storage file (cdrom0_db).

Page updated: