migrate.h File Reference

Schema migration system with version history and rollback. More...

#include <sqlite3.h>

Include dependency graph for migrate.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_migration_t
	A single migration step. More...

Macros
#define	CWIST_MIGRATE_OK   0
	Return codes.
#define	CWIST_MIGRATE_ERR_GENERIC   (-1)
#define	CWIST_MIGRATE_ERR_SQL   (-2)
#define	CWIST_MIGRATE_ERR_ARGS   (-3)

Typedefs
typedef struct cwist_migration_t	cwist_migration_t
	A single migration step.

Functions
int	cwist_migrate_up (sqlite3 *db, const cwist_migration_t *migrations, int count)
	Apply all migrations whose version > current schema version.
int	cwist_migrate_down (sqlite3 *db, const cwist_migration_t *migrations, int count, int steps)
	Roll back the most recent steps migrations.
int	cwist_migrate_version (sqlite3 *db)
	Return the highest version number that has been applied.

Detailed Description

Schema migration system with version history and rollback.

Each migration is a (version, name, up_sql, down_sql) tuple. The system stores applied migrations in a _cwist_migrations table and executes UP or DOWN SQL inside transactions, so a failed migration leaves the database unchanged.

Definition in file migrate.h.

Macro Definition Documentation

CWIST_MIGRATE_ERR_ARGS

#define CWIST_MIGRATE_ERR_ARGS   (-3)

Definition at line 20 of file migrate.h.

CWIST_MIGRATE_ERR_GENERIC

#define CWIST_MIGRATE_ERR_GENERIC   (-1)

Definition at line 18 of file migrate.h.

CWIST_MIGRATE_ERR_SQL

#define CWIST_MIGRATE_ERR_SQL   (-2)

Definition at line 19 of file migrate.h.

CWIST_MIGRATE_OK

#define CWIST_MIGRATE_OK   0

Return codes.

Definition at line 17 of file migrate.h.

Typedef Documentation

cwist_migration_t

typedef struct cwist_migration_t cwist_migration_t

A single migration step.

• version : monotonically increasing integer (e.g. 1, 2, 3 …)
• name : human-readable label (used in history table)
• up_sql : SQL executed when migrating forward; may contain multiple statements separated by ';'
• down_sql: SQL executed when rolling back; NULL means irreversible

Function Documentation

cwist_migrate_down()

int cwist_migrate_down	(	sqlite3 *	db,
		const cwist_migration_t *	migrations,
		int	count,
		int	steps
	)

Roll back the most recent steps migrations.

Runs each migration's down_sql inside a transaction and removes the entry from the history table. Irreversible migrations (down_sql == NULL) are skipped entirely: they stay in the history table, so a later cwist_migrate_up will not re-apply them, and they do not count towards steps.

Parameters

db	Open SQLite3 handle.
migrations	Array of migrations (same array passed to cwist_migrate_up).
count	Number of elements in migrations.
steps	Number of versions to roll back (0 = all applied).

Returns

CWIST_MIGRATE_OK on success, negative on failure.

Roll back the most recent steps migrations.

Parameters

db	SQLite connection to migrate.
migrations	Caller-supplied migration array.
count	Number of entries in migrations.
steps	Maximum number of applied versions to roll back, or all when <= 0.

Returns

CWIST_MIGRATE_OK on success, or a specific migration error code.

Definition at line 174 of file migrate.c.

References count, CWIST_MIGRATE_ERR_ARGS, CWIST_MIGRATE_ERR_GENERIC, CWIST_MIGRATE_ERR_SQL, CWIST_MIGRATE_OK, and cwist_migrate_version().

cwist_migrate_up()

int cwist_migrate_up	(	sqlite3 *	db,
		const cwist_migration_t *	migrations,
		int	count
	)

Apply all migrations whose version > current schema version.

Migrations are applied in ascending version order inside individual transactions. On failure the transaction is rolled back and the function returns the error code.

Parameters

db	Open SQLite3 handle.
migrations	Array of migrations (need not be sorted; function sorts).
count	Number of elements in migrations.

Returns

CWIST_MIGRATE_OK on success, negative on failure.

Apply all migrations whose version > current schema version.

Parameters

db	SQLite connection to migrate.
migrations	Caller-supplied migration array.
count	Number of entries in migrations.

Returns

CWIST_MIGRATE_OK on success, or a specific migration error code.

Definition at line 123 of file migrate.c.

References count, CWIST_MIGRATE_ERR_ARGS, CWIST_MIGRATE_ERR_GENERIC, CWIST_MIGRATE_ERR_SQL, CWIST_MIGRATE_OK, and cwist_migrate_version().

cwist_migrate_version()

int cwist_migrate_version

(

sqlite3 *

db

)

Return the highest version number that has been applied.

Returns

Version number, or 0 if no migrations have been applied, or -1 on error.

Return the highest version number that has been applied.

Parameters

db	SQLite connection to inspect.

Returns

Highest applied version, or -1 when the query fails.

Definition at line 99 of file migrate.c.

References CWIST_MIGRATE_OK.

Referenced by cwist_migrate_down(), and cwist_migrate_up().