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).