Firfuorida::Migration Class Reference

Contains a single migration instance. More...

#include <Firfuorida/Migration>

Inheritance diagram for Firfuorida::Migration:

Public Member Functions
	Migration (Migrator *parent)
	Constructs a new Migration object with the given parent.
	~Migration () override
	Deconstructs the Migration object.

Protected Member Functions
Table *	create (const QString &tableName)
	Creates a new table with the given tableName.
Table *	createTableIfNotExists (const QString &tableName)
	Creates a new table with the given tableName if it not exists already.
Migrator::DatabaseFeatures	dbFeatures () const
	Returns features supported by the used datbase system.
Migrator::DatabaseType	dbType () const
	Returns the type of the used database system.
QString	dbTypeToStr () const
	Returns the name of the used database system.
QVersionNumber	dbVersion () const
	Returns the version of the used database system.
virtual void	down ()=0
	Reimplement this function to perform database operations when performing migration rollback.
void	drop (const QString &tableName)
	Drops the table identified by tableName.
void	dropIfExists (const QString &tableName)
	Drops the table identified by tableName if it exists.
bool	isDbFeatureAvailable (Migrator::DatabaseFeatures dbFeatures) const
	Returns true if the dbFeatures are available on the used database system.
Error	lastError () const
	Returns error information about the last error (if any) that occurred with this migrator.
void	raw (const QString &statement)
	Executes a raw SQL statement.
void	rename (const QString &tableName, const QString &newName)
	Renames the table named tableName to newName.
Table *	table (const QString &tableName)
	Returns an existing Table object for a table with the given tableName.
virtual void	up ()=0
	Reimplement this function to perform database operations when performing migrations.

Detailed Description

Contains a single migration instance.

The Migration object represents a single migration instance. A migration is defined by operations defined in the reimplemented up() and down() functions. The reimplemented up() function is called when the migration is done. The reimplemented down() function is called when the migrations will be rolled back. Inside up() and down() use the create(), createTableIfNotExists(), table(), drop(), dropIfExists(), rename() and raw() functions.

Additionally there is the possibility to use a custom function for migration by reimplenting executeUp() and executeDown().

Example

example.h

/*
 * SPDX-FileCopyrightText: (C) 2019-2022 Matthias Fehring <https://www.huessenbergnetz.de>
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 
#include <Firfuorida/Migration>
 
class M20190121T174100_Example : public Firfuorida::Migration
{
    Q_OBJECT
public:
    explicit M20190121T174100_Example(Firfuorida::Migrator *parent);
    ~M20190121T174100_Example() override;
 
protected:
    void up() override;
    void down() override;
}

example.cpp

/*
 * SPDX-FileCopyrightText: (C) 2019-2022 Matthias Fehring <https://www.huessenbergnetz.de>
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 
#include "example.h"
 
M20190121T174100_Example::M20190121T174100_Example(Firfuorida::Migrator *parent) :
    Firefuorida::Migration(parent)
{
}
 
M20190121T174100_Example::~M20190121T174100_Example()
{
}
 
void M20190121T174100_Example::up()
{
    // create a new table named "ExampleTable" if it not already exists
    auto t = createTableIfNotExists(QStringLiteral("ExampleTable"));
    // create a new unsigned tiny integer column on that table with the
    // default name "id" and auto incrementation enabled
    t->tinyIncrements();
    // create a new signed tiny integer column on that table with the
    // name "tinyIntCol" and UNIQUE KEY index.
    t->tinyInteger(QStringLiteral("tinyIntCol"))->unique();
    // create a new nullable tiny blob column on that table with the name
    // "tinyBlobCol"
    t->tinyBlob(QStringLiteral("tinyBlobCol"))->nullable();
    // create a new tiny text column on that table with the name "tinyTextCol"
    // and the default value "foobar"
    t->tinyText(QStringLiteral("tinyTextCol"))->defaultValue(QStringLiteral("foobar"));
}
 
void M20190121T174100_Example::down()
{
    // drop the table named "ExampleTable" if it exists
    dropIfExists(QStringLiteral("ExampleTable"));
}

main.cpp

/*
 * SPDX-FileCopyrightText: (C) 2019-2022 Matthias Fehring <https://www.huessenbergnetz.de>
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 
#include <QCoreApplication>
#include <QSqlDatabase>
#include <Firfuorida/Migrator>
#include "example.h"
 
int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
 
    // add an SQL connection ...
 
    // create a new Migrator object for the default connection that
    // stores the applied migrations in the "migrations" table
    auto migrator = new Firfuorida::Migrator(QLatin1String(QSqlDatabase::defaultConnection), QStringLiteral("migrations"), &app);
 
    // add the example migration to the migrator
    new M20190121T174100_Example(migrator);
 
    // run migrations, return non zero value on error
    if (!migrator->migrate()) {
        return 1;
    }
 
    // roll back all migrations, return non zero value on error
    if (!migrator->rollback(0)) {
        return 1;
    }
 
    return 0;
}

Constructor & Destructor Documentation

Migration()

Migration::Migration ( Migrator * parent )

explicit

Constructs a new Migration object with the given parent.

The parent has to be a valid Migrator object.

~Migration()

Migration::~Migration ( )

override

Deconstructs the Migration object.

Member Function Documentation

create()

Table * Migration::create ( const QString & tableName )

protected

Creates a new table with the given tableName.

The tableName is not allowed to be empty. Use the returned Table object to create columns on it.

See also

createTableIfNotExists()

createTableIfNotExists()

Table * Migration::createTableIfNotExists ( const QString & tableName )

protected

Creates a new table with the given tableName if it not exists already.

The tableName is not allowed to be empty. Use the returned Table object to create columns on it.

See also

create()

dbFeatures()

Migrator::DatabaseFeatures Migration::dbFeatures ( ) const

protected

Returns features supported by the used datbase system.

Note

This is only availbale after Migrator::initDatabase(), Migrator::migrate() or Migrator::rollback() has been called.

dbType()

Migrator::DatabaseType Migration::dbType ( ) const

protected

Returns the type of the used database system.

Note

This is only availbale after Migrator::initDatabase(), Migrator::migrate() or Migrator::rollback() has been called.

dbTypeToStr()

QString Migration::dbTypeToStr ( ) const

protected

Returns the name of the used database system.

Note

This is only availbale after Migrator::initDatabase(), Migrator::migrate() or Migrator::rollback() has been called.

dbVersion()

QVersionNumber Migration::dbVersion ( ) const

protected

Returns the version of the used database system.

Note

This is only availbale after Migrator::initDatabase(), Migrator::migrate() or Migrator::rollback() has been called.

down()

virtual void Firfuorida::Migration::down ( )

protectedpure virtual

Reimplement this function to perform database operations when performing migration rollback.

Example

void M20190121T174100_Example::down()
{
    // drop the table named "ExampleTable" if it exists
    dropIfExists(QStringLiteral("ExampleTable"));
}

See also

up()

drop()

void Migration::drop ( const QString & tableName )

protected

Drops the table identified by tableName.

See also

dropIfExists()

dropIfExists()

void Migration::dropIfExists ( const QString & tableName )

protected

Drops the table identified by tableName if it exists.

See also

drop()

isDbFeatureAvailable()

bool Migration::isDbFeatureAvailable ( Migrator::DatabaseFeatures dbFeatures ) const

protected

Returns true if the dbFeatures are available on the used database system.

Note

This is only availbale after Migrator::initDatabase(), Migrator::migrate() or Migrator::rollback() has been called.

lastError()

Error Migration::lastError ( ) const

protected

Returns error information about the last error (if any) that occurred with this migrator.

raw()

void Migration::raw ( const QString & statement )

protected

Executes a raw SQL statement.

rename()

void Migration::rename ( const QString & tableName, const QString & newName )

protected

Renames the table named tableName to newName.

table()

Table * Migration::table ( const QString & tableName )

protected

Returns an existing Table object for a table with the given tableName.

The tableName is not allowed to be empty. Use the returned Table object to modify or crate columns on it.

up()

virtual void Firfuorida::Migration::up ( )

protectedpure virtual

Reimplement this function to perform database operations when performing migrations.

Example

void M20190121T174100_Example::up()
{
    // create a new table named "ExampleTable" if it not already exists
    auto t = createTableIfNotExists(QStringLiteral("ExampleTable"));
    // create a new unsigned tiny integer column on that table with the
    // default name "id" and auto incrementation enabled
    t->tinyIncrements();
    // create a new signed tiny integer column on that table with the
    // name "tinyIntCol" and UNIQUE KEY index.
    t->tinyInteger(QStringLiteral("tinyIntCol"))->unique();
    // create a new nullable tiny blob column on that table with the name
    // "tinyBlobCol"
    t->tinyBlob(QStringLiteral("tinyBlobCol"))->nullable();
    // create a new tiny text column on that table with the name "tinyTextCol"
    // and the default value "foobar"
    t->tinyText(QStringLiteral("tinyTextCol"))->defaultValue(QStringLiteral("foobar"));
}

See also

down()