Configuring Database Behavior

This chapter describes how to add and remove indexes for the MME database, and the database configuration elements that set:

This chaper includes:

For information about how to configuring QDB to backup MME databases, see the chapter Backing up and Restoring MME Databases.

Database configuration elements

All database configuration elements are under the elements <Configuration>/<Database>. The table below lists database configuration elements.

Element Attributes Default Description
<CharacterEncodingConverter> dll n/a A custom DLL to perform character encoding conversions. See Creating an external DLL to provide character encoding routines in the chapter Configuring Internationalization.
<Mountpath> /dev/qdb/mme The path to the MME database. See Database mountpath below.
<TimebaseSet> enabled false Automatically adjust the internal timebase for the MME. See Database time base below.
<Timeout> 0 The database timeout (in milliseconds). See Database timeout below.

Database mountpath

You can configure the mountpath to the MME database, and a timeout setting for the database. The mountpath is the location of the MME database. The default path is /dev/qdb/mme. To change it, change the path in the element <Configuration>/<Database>/<Mountpath>.

Database time base

For systems that do not have a stable real-time clock, enable the <TimebaseSet> option. Enabling this option causes the MME to run a routine that adjusts its internal timebase so that all time values used in the database increase monotonically. If this configuration is enabled, the adjustment routine is run before creation of the MME's path.

See also mme_timebase_set() in the MME API Library Reference.

Database timeout

The database timeout is the number of milliseconds the database has to complete a request before it fails and returns an error. The default setting is 0 (zero), which disables the timeout. There is no limit on the time the database can use to complete requests.

To enable the database timeout feature, change the value of <Timeout> to the number of milliseconds you want to give the database to complete requests.


Caution: With the timeout feature enabled, database operations that take longer than the timeout period will create errors. Tune the timeout value to meet the needs of your environment, and ensure that your client application handles timeout errors appropriately.

Adding and removing indexes

Indexes can be created on any table for any number of columns, using the CREATE INDEX statement in a schema, or in your application. Indexes are used automatically by QDB if they are there. An index speeds up any operation where the indexed field is used in a WHERE, ORDER BY or GROUP BY clause. However, the index will slow down any operation that modifies the indexed field.

You should remove indexes your client application doesn't use, and add indexes that will increase performance. Performance can be greatly increased when reading from tables if the columns that are being used for WHERE and ORDER BY have an index. PRIMARY KEY columns do not need an index created on them.

For more information about using indexes to optimize performance, see Using indexes to optimize synchronization performance in the chapter MME Configuration Tips and Troubleshooting.

Database pruning

Prune management is a technique for “pruning” (deleting) unused data to ensure that a database doesn't grow too large or exceed a specified size. The MME prunes its database:

You can set values for the pruning configuration elements that control pruning behavior in mme.conf.

The table below lists database pruning configuration elements. All pruning elements are under the elements <Configuration>/<Database>/<Prune>.

Element Attributes Default Description
<MaxDatabaseSize> 0 The “high-water mark” for the MME database (in kilobytes). If the MME database exceeds this size, the MME's pruning managers will attempt to prune the database. Set to 0 (zero) to disable.
<MediastoreMatching> 0 Identify unavailable mediastore types for pruning. See Pruning options for unavailable mediastores below.
<SyncInterval> 0 Check the size of the MME database after this number of files have been synchronized. Set to 0 (zero) to disable.
<WhenUnavailable> OnEject false Determines if the MME automatically prunes entries from its database when mediastores of the specified types are ejected. See Pruning options for unavailable mediastores below.

Note:
  • You can mark specific files, such as ringtone files, as permanent, so that the MME will never prune them. See mme_set_files_permanent() in the MME API Library Reference.
  • You can use mme_delete_mediastores() to prune from the MME database entries for mediastores whose state is unavailable, regardless of the settings of <WhenUnavailable>.

Maximum database size

The element <MaxDatabaseSize> sets the maximum size in kilobytes of the MME database. During a synchronization, the MME checks the database size periodically, at the interval set by <SyncInterval>. If the database exceeds the size set by <MaxDatabaseSize>, the MME attempts to prune the database. It performs the following steps in order until the database size is reduced below the maximum allowed:

  1. Clean up the database file structure by calling qdb_vacuum().
  2. Delete unavailable mediastores and any associated content.
  3. Stop synchronization. In this case, the last synchronized mediastore is only partially synchronized, though it is considered available, and all synchronized content can be played.

Note: The MME checks its database size only when performing synchronizations, at the interval specified by the <SyncInterval> element.

Interval for checking database size

You can configure the MME to check the size of its database during pruning. Configure this setting by changing the value in the <SyncInterval> element in the mme.conf configuration file. The default is 0 (zero): do not check the database size until a synchronization is complete.

If you enable this feature, consider the following impacts on performance:

Pruning options for unavailable mediastores

The MME includes options for managing how mediastore entries are pruned from the MME database:

About pruning ejected mediastores

Entries for mediastores can be pruned from the MME database by one of the following methods:

The MME or the client application calling mme_delete_mediastores() can prune mediastore entries from the MME database when the following conditions are met:

The MME's automatic pruning behavior for ejected mediastores is as follows:


Note:
  • The <WhenUnavailable> and <MediastoreMatching> configuration elements do not affect pruning activities initiated by the MME to keep its database size within configured limits.
  • When the MME is configured to not prune entries for ejected mediastores from its database, the state of an ejected mediastore is set to unavailable.

<WhenUnavailable>

The <WhenUnavailable> configuration element determines if the MME automatically prunes entries from its database when mediastores of the specified types become unavailable (are ejected from the system).

The <WhenUnavailable> element has one attribute: OnEject, and can contain multiple <MediastoreMatching> elements:

The default setting for the OnEject attribute is false: don't automatically prune mediastore entries from the MME database when mediastores are ejected from the system.

The example below shows the configuration for automatically pruning library entries for ejected mediastores of type MME_STORAGETYPE_FS (2) and MME_STORAGETYPE_DVDVIDEO (6) when these types of mediastores are ejected from the system:

<Database>
	...
    <Prune>
    ...
		<WhenUnavailable OnEject="true">
				<MediastoreMatching storagetype="2"/>
				<MediastoreMatching storagetype="6"/>

		</WhenUnavailable>
    </Prune>
</Database>

Note: The <WhenUnavailable> element does not effect automatic pruning conducted by the MME to maintain its database size within configured limits.

<MediastoreMatching>

The <MediastoreMatching> configuration element identifies mediastore types for which entries for unavailable mediastores can be pruned from the MME database by the MME's automatic pruning or by the client application calling mme_delete_mediastores().

For each mediastore type for which you want to delete entries from the the MME database when a mediastore is ejected, create a <MediastoreMatching> element and set its storagetype attribute to the appropriate MME_STORAGETYPE_* value. See MME_STORAGETYPE_* in the MME Developer's Guide for a complete list of MME_STORAGETYPE_* values.

For example, the following configuration would prune audio CDs (1), disk-based mediastores (2), audio DVDs (3), video DVDs (6), and iPods (8):

<WhenUnavailable OnEject="true">
    <MediastoreMatching storagetype="1"/>
    <MediastoreMatching storagetype="2"/>
    <MediastoreMatching storagetype="3"/>
    <MediastoreMatching storagetype="6"/>
    <MediastoreMatching storagetype="8"/>
</WhenUnavailable>

Sample script mme_del_unav

The sample script below instructs the MME to delete all unavailable mediastores, subject to the restrictions set by the <MediastoreMatching> configuration elements.

mme_del_unav

#!/bin/ksh
#
# This script is used to tell the MME to delete all unavailable media stores.
#
# If the MME is not available when the script is executed, it does one of two
# things, depending on the use of the '-nowait' directive.
# If the -nowait directive is specified, the script returns an error.
# If the -wait directive is specified, it waits for the path for the number
# of seconds in the time-out value. When connected, it then waits for the
# same time before executing the command.

# Change this to set the default wait time without using a parameter.
DEF_WAIT_TIME=60

# Set defaults
MME_PATH=/dev/mme/default
QDB_PATH=/dev/qdb/mme
WAIT_TIME=DEF_WAIT_TIME
SHOW_HELP=0

# Collect options
while getopts d:m:w:h o ; do
   case $o in
   d) QDB_PATH=$OPTARG;;
   m) MME_PATH=$OPTARG;;
   w) WAIT_TIME=$OPTARG;;
   h) SHOW_HELP=1
   esac
done
shift $OPTIND-1

# The help message output...
usage () {
    echo "$0 - a utility to tell the MME to delete all unavailable media stores"
    echo "Usage: $0 -h | [ [-m <MME path>] [-d <QDB path>] [-w <seconds>] ]"
    echo "where:"
    echo " -m <MME path> is the path to the MME (default \"/dev/mme/default\")"
    echo " -d <QDB path> is the path to the QDB database (default \"/dev/qdb/mme\")"
    echo " -w <seconds> is the number of seconds for two things."
    echo "    First, it's the maximum time it will wait to connect to the MME"
    echo "    if it's not available when the script start."
    echo "    Second, it's the maximum time it will wait after connecting"
    echo "    to the MME before telling it to delete unavailable."
    echo "    media stores (default $DEF_WAIT_TIME)"
    echo " -h prints this"
}

# If help requested, only do that.
if [ $SHOW_HELP -eq 1 ]
then
    usage
    return 0
fi

# The command to be executed.
CMD="mmecli -c $MME_PATH -d $QDB_PATH delete_mediastores"

# Do it now if not supposed to wait.
if [ $WAIT_TIME -eq 0 ]
then
    $CMD
    return $?
fi

# Wait on the path.
waitfor $MME_PATH $WAIT_TIME
if [ $? -ne 0 ]
then
    # Already logged by waitfor
    return $?
fi

# Path was good, wait the required time.
sleep $WAIT_TIME
if [ $? -ne 0 ]
then
    # Don't know if this is already logged!
    echo "Error sleeping..."
    return $?
fi

# Path was good and waited the required time, so execute the command
$CMD
return $?

Database constants

The table below lists the constants in config.h with the MME compile-time settings for database management.

Constant Value Description
CONFIG_DEF_MAX_DATABASE_SIZE 0 The database size, in kilobytes, above which the MME triggers prune management. See Maximum database size above. Set to 0 (zero) to disable.
CONFIG_DEF_SYNC_INTERVAL 0 The number of files to synchronize before checking database size against maximum allowed. See Interval for checking database size above. Set to 0 (zero) to disable.
CONFIG_DEF_DATABASE_MOUNTPATH /dev/qdb/mme The default path to the MME's database.
CONFIG_DEF_DATABASE_MOUNTPATH_LEN 256 The maximum length, in bytes, for the MME's database mountpath
CONFIG_DEF_DATABASE_SETNAME mme The database backup name.
CONFIG_DEF_DATABASE_SETNAME_LENGTH 32 The maximum length, in bytes, of the name of a database backup set.
CONFIG_DEF_DATABASE_TIMEOUT_MS 0 The timeout setting for database access, in milliseconds. Set to 0 (zero) to disable.