Database configuration objects

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.

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.

Filename::/root/tmp/cdrom0_db
SchemaFile::/etc/mm/sql/mmsync.sql
DataSchemaFile::/etc/mm/sql/mmsync_data.sql