Function

Purplesqlite3_run_migrations_from_strings

Declaration [src]

gboolean
purple_sqlite3_run_migrations_from_strings (
  PurpleSqlite3* db,
  const char** migrations,
  GError** error
)

Description [src]

Runs the given migrations in the order they are given. The index of each migration plus 1 is assumed is to be the version number of the migration, which means that you can not change the order of the migrations. The reasoning for the addition of 1 is because PRAGMA user_version defaults to 0.

This expects each string in migrations to be a complete migration. That is, each string in the array should contain all of the SQL for that migration. For example, if you’re expecting to have 2 migrations, the initial creating two tables, and then adding a column to one of the existing tables, you would have something like the following code.

const char *migrations[] = {
    // Our initial migration that creates user and session tables.
    "CREATE TABLE user(id INTEGER PRIMARY KEY, name TEXT);"
    "CREATE TABLE session(user INTEGER, token TEXT) FOREIGN KEY(user) REFERENCES user(id);",
    // Begin our second migration that will add a display name to the user
    // table. Note the ',' at the end of the previous line.
    "ALTER TABLE user ADD COLUMN(display_name TEXT);",
    NULL
};

Also, this function will run each migration in its own transaction so you don’t need to worry about them. This is done to make sure that the database stays at a known version and an incomplete migration will not be saved.

Available since:3.0.0

Parameters

db PurpleSqlite3
 

The sqlite3 connection.

 The data is owned by the caller of the function.
migrations An array of char*
 

A list of SQL statements, each item being its own migration.

 The array must be NULL-terminated.
 The data is owned by the caller of the function.
 Each element is a NUL terminated UTF-8 string.
error GError **
  The return location for a GError*, or NULL.

Return value

Returns: gboolean
 

TRUE on success, or FALSE on error potentially with error set.