Firfuorida::Migrator Class Reference

Manages multiple migrations. More...

#include <Firfuorida/Migrator>

Inheritance diagram for Firfuorida::Migrator:

Public Types
enum	DatabaseFeature : int {   NoFeatures = 1 << 0 , DefValOnText = 1 << 1 , DefValOnBlob = 1 << 2 , DefValOnGeometry = 1 << 3 ,   JSONTypes = 1 << 4 , GeometryTypes = 1 << 5 , XMLType = 1 << 6 , NetworkAddressTypes = 1 << 7 ,   MonetaryTypes = 1 << 8 , ForeignKeys = 1 << 9 , CommentsOnColumns = 1 << 10 , CommentsOnTables = 1 << 11 ,   SetType = 1 << 12 , EnumType = 1 << 13 , UnsignedInteger = 1 << 14 , CharsetOnColumn = 1 << 15 ,   YearType = 1 << 16 }
	Features supported by the currently used database system. More...
enum	DatabaseType : uint8_t {   Invalid = 0 , DB2 = 1 , InterBase = 2 , MySQL = 3 ,   MariaDB = 5 , ODBC = 6 , OCI = 7 , PSQL = 8 ,   SQLite = 9 }
	These are the database systems supported by default by Qt. More...

Public Member Functions
	Migrator (const QString &connectionName, const QString &migrationsTable, QObject *parent=nullptr)
	Constructs a new Migrator object with the given parameters.
	Migrator (QObject *parent=nullptr)
	Constructs a new Migrator object with default values and given parent.
	~Migrator ()
	Deconstructs the Migrator object.
QString	connectionName () const
	Returns the name of the used SQL connection.
DatabaseFeatures	dbFeatures () const
	Returns features supported by the used datbase system.
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.
bool	initDatabase ()
	Opens and initializes the database.
bool	isDbFeatureAvailable (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.
bool	migrate ()
	Runs all migrations not already applied and return true on success.
QString	migrationsTable () const
	Returns the name of the table to store migrations to.
bool	refresh (uint steps=0)
	Rolls back and reapplies the number of migrations defined by steps.
bool	reset ()
	Rolls back all migrations and returns true on success.
bool	rollback (uint steps=1)
	Rolls back the number of migrations set by steps and returns true on success.

Detailed Description

Manages multiple migrations.

The Migrator class manages multiple Migration objects that are children of the Migrator class.

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;
}

Member Enumeration Documentation

DatabaseFeature

enum Firfuorida::Migrator::DatabaseFeature : int

Features supported by the currently used database system.

See also

dbFeatures(), isDbFeatureAvailable()

Enumerator
NoFeatures	No special features are available.
DefValOnText	Supports default values on text type columns.
DefValOnBlob	Supports default values on blob type columns.
DefValOnGeometry	Supports default values on geometry type columns.
JSONTypes	Supports JSON data types.
GeometryTypes	Supports geometry data types.
XMLType	Supports XML data types.
NetworkAddressTypes	Supports network address data types.
MonetaryTypes	Supports monetary data types.
ForeignKeys	Supports foreign key constraints.
CommentsOnColumns	Supports comments on columns.
CommentsOnTables	Supports comments on tables.
SetType	Supports SET data type.
EnumType	Supports ENUM data type.
UnsignedInteger	Supports unsigned integer data types.
CharsetOnColumn	Supports character set on columns.
YearType	Support the YEAR data type.

DatabaseType

enum Firfuorida::Migrator::DatabaseType : uint8_t

These are the database systems supported by default by Qt.

Enumerator
Invalid	No valid database diver/type has been set.
DB2	IBM DB2 (version 7.1 and above)
InterBase	Borland InterBase
MySQL	MySQL
MariaDB	MariaDB (version 5.0 and above)
ODBC	Open Database Connectivity (ODBC) - Microsoft SQL Server and other ODBC-compliant databases
OCI	Oracle Call Interface Driver
PSQL	PostgreSQL (versions 7.3 and above)
SQLite	SQLite version 3

Constructor & Destructor Documentation

Migrator() [1/2]

Migrator::Migrator ( QObject * parent = nullptr )

explicit

Constructs a new Migrator object with default values and given parent.

Uses QSqlDatabase::defaultConnection as connectionName and "migrations" as migrationsTable.

Migrator() [2/2]

Migrator::Migrator ( const QString & connectionName, const QString & migrationsTable, QObject * parent = nullptr )

explicit

Constructs a new Migrator object with the given parameters.

Parameters

connectionName	The name of the SQL connection to use.
migrationsTable	The name of the table to store the migrations in.
parent	Pointer to a parent object.

~Migrator()

Migrator::~Migrator ( )

default

Deconstructs the Migrator object.

Member Function Documentation

connectionName()

QString Migrator::connectionName

(

)

const

Returns the name of the used SQL connection.

dbFeatures()

Migrator::DatabaseFeatures Migrator::dbFeatures

(

)

const

Returns features supported by the used datbase system.

Note

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

dbType()

Migrator::DatabaseType Migrator::dbType

(

)

const

Returns the type of the used database system.

Note

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

dbTypeToStr()

QString Migrator::dbTypeToStr

(

)

const

Returns the name of the used database system.

Note

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

dbVersion()

QVersionNumber Migrator::dbVersion

(

)

const

Returns the version of the used database system.

Note

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

initDatabase()

bool Migrator::initDatabase

(

)

Opens and initializes the database.

If the databae is not already open, this will try to open it. After that it will set the dbType(), the dbVersion() and the dbFeatures(). This has not to be called explicitely but is called by migrate() and rollback() automatically.

isDbFeatureAvailable()

bool Migrator::isDbFeatureAvailable

(

DatabaseFeatures

dbFeatures

)

const

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

Note

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

lastError()

Error Migrator::lastError

(

)

const

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

migrate()

bool Migrator::migrate

(

)

Runs all migrations not already applied and return true on success.

If an error occures, false will be returned. Use lastError() to see what happened.

migrationsTable()

QString Migrator::migrationsTable

(

)

const

Returns the name of the table to store migrations to.

refresh()

bool Migrator::refresh

(

uint

steps = 0

)

Rolls back and reapplies the number of migrations defined by steps.

If steps is 0, all migrations are rolled back and reapplied. If an error occures, false will be returned. Use lastError() to see what happened.

reset()

bool Migrator::reset

(

)

Rolls back all migrations and returns true on success.

If an error occures, false will be returned. Use lastError() to see what happened.

rollback()

bool Migrator::rollback

(

uint

steps = 1

)

Rolls back the number of migrations set by steps and returns true on success.

If steps is 0, only one migration will be rolled back. If an error occures, false will be returned. Use lastError() to see what happened.