DBUtil Class Reference

Aggregates database and DBMS utility functions. More...

#include <dbutil.h>

Inheritance diagram for DBUtil:

Public Member Functions
	DBUtil ()
	Constructs the DBUtil object.
	~DBUtil ()
QString	GetDBMSVersion (void)
	Returns the QString version name of the DBMS or QString::null in the event of an error.
int	CompareDBMSVersion (int major, int minor=0, int point=0)
	Compares the version of the active DBMS with the provided version.
MythDBBackupStatus	BackupDB (QString &filename, bool disableRotation=false)
	Requests a backup of the database.
Static Public Member Functions
static bool	CheckTables (const bool repair=false, const QString options="QUICK")
	Checks database tables.
static bool	RepairTables (const QStringList &tables)
	Repairs database tables.
static bool	IsNewDatabase (void)
	Returns true for a new (empty) database.
static bool	IsBackupInProgress (void)
	Test to see if a DB backup is in progress.
static int	CountClients (void)
	Estimate the number of MythTV programs using the database.
static bool	TryLockSchema (MSqlQuery &, uint timeout_secs)
	Try to get a lock on the table schemalock.
static void	UnlockSchema (MSqlQuery &)
Static Public Attributes
static const int	kUnknownVersionNumber = INT_MIN
Static Protected Member Functions
static bool	CreateTemporaryDBConf (const QString &privateinfo, QString &filename)
	Creates temporary file containing sensitive DB info.
Private Member Functions
bool	QueryDBMSVersion (void)
	Reads and returns the QString version name from the DBMS or returns QString::null in the event of an error.
bool	ParseDBMSVersion (void)
	Parses m_versionString to find the major, minor, and point version.
QString	CreateBackupFilename (QString prefix="mythconverg", QString extension=".sql")
	Creates a filename to use for the filename.
QString	GetBackupDirectory ()
	Determines the appropriate path for the database backup.
bool	DoBackup (const QString &backupScript, QString &filename, bool disableRotation=false)
bool	DoBackup (QString &filename)
	Creates a backup of the database.
Static Private Member Functions
static QStringList	GetTables (const QStringList &engines=QStringList())
	Retrieves a list of tables from the database.
static QStringList	CheckRepairStatus (MSqlQuery &query)
	Parse the results of a CHECK TABLE or REPAIR TABLE run.
Private Attributes
QString	m_versionString
int	m_versionMajor
int	m_versionMinor
int	m_versionPoint

Detailed Description

Aggregates database and DBMS utility functions.

This class allows retrieving or comparing the DBMS server version, and backing up the database.

The backup functionality currently requires mysqldump to be installed on the system. This may change in the future to allow backups even when there is no DB client installation on the system.

See also:: HouseKeeper::RunHouseKeeping(void)

Definition at line 30 of file dbutil.h.

Constructor & Destructor Documentation

DBUtil::DBUtil ( void )

Constructs the DBUtil object.

Definition at line 32 of file dbutil.cpp.

DBUtil::~DBUtil ( ) [inline]

Definition at line 34 of file dbutil.h.

Member Function Documentation

QString DBUtil::GetDBMSVersion ( void )

Returns the QString version name of the DBMS or QString::null in the event of an error.

Definition at line 42 of file dbutil.cpp.

Referenced by SchemaUpgradeWizard::PromptForUpgrade().

int DBUtil::CompareDBMSVersion	(	int	major,
		int	minor = `0`,
		int	point = `0`
	)

Compares the version of the active DBMS with the provided version.

Returns negative, 0, or positive if the active DBMS version is less than, equal to, or greater than the provided version or returns DBUtil::kUnknownVersionNumber if the version cannot be determined.

Parameters:

	major	The major version number (i.e. 5 in "5.0.22")
	minor	The minor version number (i.e. 0 in "5.0.22")
	point	The point version number (i.e. 22 in "5.0.22")

Returns:: negative, 0, or positive or DBUtil::kUnknownVersionNumber for error

Definition at line 61 of file dbutil.cpp.

Referenced by SchemaUpgradeWizard::PromptForUpgrade().

MythDBBackupStatus DBUtil::BackupDB	(	QString &	filename,
		bool	disableRotation = `false`
	)

Requests a backup of the database.

If the DatabaseBackupScript exists in the ShareDir, it will be executed. All required database information will be made available as name=value pairs in a temporary file whose filename will be passed to the backup script. The script may parse this file to obtain the required information to run a backup program, such as mysqldump or mysqlhotcopy.

If the DatabaseBackupScript does not exist, a backup will be performed using mysqldump directly. The database password will be passed in a temporary file so it does not have to be specified on the command line.

Care should be taken in calling this function. It has the potential to corrupt in-progress recordings or interfere with playback.

The disableRotation argument should be used only for automatic backups when users could lose important backup files due to a failure loop--for example, a DB upgrade failure and a distro start script that keeps restarting mythbackend even when it exits with an error status.

Parameters:

	filename	Used to return the name of the resulting backup file
	disableRotation	Disable backup rotation

Returns:: MythDBBackupStatus indicating the result

Definition at line 205 of file dbutil.cpp.

Referenced by Myth::BackupDatabase().

bool DBUtil::CheckTables	(	const bool	repair = `false`,
		const QString	options = `"QUICK"`
	)			`[static]`

Checks database tables.

This function will check database tables.

Parameters:

	repair	Repair any tables whose status is not OK
	options	Options to be passed to CHECK TABLE; defaults to QUICK

Returns:: false if any tables have status other than OK; if repair is true, returns true if those tables were repaired successfully

See also:: DBUtil::RepairTables(const QStringList)

Definition at line 293 of file dbutil.cpp.

Referenced by Myth::CheckDatabase().

bool DBUtil::RepairTables ( const QStringList & tables ) [static]

Repairs database tables.

This function will repair MyISAM database tables.

Care should be taken in calling this function. It should only be called when no clients are accessing the database, and in the event the MySQL server crashes, it is critical that a REPAIR TABLE is run on the table that was being processed at the time of the server crash before any other operations are performed on that table, or the table may be destroyed. It is up to the caller of this function to guarantee the safety of performing database repairs.

Parameters:

tables

List of tables to repair

Returns:: false if errors were encountered repairing tables

See also:: DBUtil::CheckTables(const bool, const QString)

Definition at line 347 of file dbutil.cpp.

Referenced by CheckTables().

bool DBUtil::IsNewDatabase ( void ) [static]

Returns true for a new (empty) database.

Definition at line 82 of file dbutil.cpp.

Referenced by BackupDB(), SchemaUpgradeWizard::Compare(), and doUpgradeTVDatabaseSchema().

bool DBUtil::IsBackupInProgress ( void ) [static]

Test to see if a DB backup is in progress.

Definition at line 96 of file dbutil.cpp.

int DBUtil::CountClients ( void ) [static]

Estimate the number of MythTV programs using the database.

Definition at line 817 of file dbutil.cpp.

Referenced by SchemaUpgradeWizard::PromptForUpgrade().

bool DBUtil::TryLockSchema	(	MSqlQuery &	query,
		uint	timeout_secs
	)			`[static]`

Try to get a lock on the table schemalock.

Prevents multiple upgrades by different programs of the same schema.

Definition at line 859 of file dbutil.cpp.

Referenced by UpgradeMusicDatabaseSchema(), and UpgradeTVDatabaseSchema().

void DBUtil::UnlockSchema ( MSqlQuery & query ) [static]

Definition at line 866 of file dbutil.cpp.

Referenced by UpgradeMusicDatabaseSchema(), and UpgradeTVDatabaseSchema().

bool DBUtil::CreateTemporaryDBConf	(	const QString &	privateinfo,
		QString &	filename
	)			`[static, protected]`

Creates temporary file containing sensitive DB info.

So we don't have to specify the password on the command line, use --defaults-extra-file to specify a temporary file with a [client] and [mysqldump] section that provides the password. This will fail if the user's ~/.my.cnf (which is read after the --defaults-extra-file) specifies a different password that's incorrect for dbUserName

Definition at line 529 of file dbutil.cpp.

Referenced by DoBackup().

bool DBUtil::QueryDBMSVersion ( void ) [private]

Reads and returns the QString version name from the DBMS or returns QString::null in the event of an error.

Definition at line 756 of file dbutil.cpp.

Referenced by GetDBMSVersion(), and ParseDBMSVersion().

bool DBUtil::ParseDBMSVersion ( void ) [private]

Parses m_versionString to find the major, minor, and point version.

Definition at line 785 of file dbutil.cpp.

Referenced by CompareDBMSVersion().

QStringList DBUtil::GetTables ( const QStringList & engines = QStringList() ) [static, private]

Retrieves a list of tables from the database.

Returns:: QStringList containing table names

Definition at line 435 of file dbutil.cpp.

Referenced by CheckTables(), and IsNewDatabase().

QStringList DBUtil::CheckRepairStatus ( MSqlQuery & query ) [static, private]

Parse the results of a CHECK TABLE or REPAIR TABLE run.

This function reads the records returned by a CHECK TABLE or REPAIR TABLE run and determines the status of the table(s). The query should have columns Table, Msg_type, and Msg_text.

The function properly handles multiple records for a single table. If the last record for a given table shows a status (Msg_type) of OK (Msg_text), the table is considered OK, even if an error or warning appeared before (this could be the case, for example, when an empty table is crashed).

Parameters:

query

An already-executed CHECK TABLE or REPAIR TABLE query whose results should be parsed.

Returns:: A list of names of not-OK (errored or crashed) tables

See also:: DBUtil::CheckTables(const bool, const QString); DBUtil::RepairTables(const QStringList)

Definition at line 394 of file dbutil.cpp.

Referenced by CheckTables(), and RepairTables().

QString DBUtil::CreateBackupFilename	(	QString	prefix = `"mythconverg"`,
		QString	extension = `".sql"`
	)			`[private]`

Creates a filename to use for the filename.

The filename is a concatenation of the given prefix, a hyphen, the current date/time, and the extension.

Parameters:

	prefix	The prefix (i.e. a database name) which should appear before the date/time
	extension	The extension to use for the file, including a dot, if desired

Returns:: QString name

Definition at line 478 of file dbutil.cpp.

Referenced by DoBackup().

QString DBUtil::GetBackupDirectory ( void ) [private]

Determines the appropriate path for the database backup.

The function requests the special "DB Backups" storage group. In the event the group is not defined, the StorageGroup will fall back to using the "Default" group. For users upgrading from version 0.20 or before (which do not support Storage Groups), the StorageGroup will fall back to using the old RecordFilePrefix.

Definition at line 494 of file dbutil.cpp.

Referenced by DoBackup().