libpurple/purplesqlite3.h

/*
 * Purple - Internet Messaging Library
 * Copyright (C) Pidgin Developers <devel@pidgin.im>
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here. Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your option)
 * any later version.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this library; if not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#endif

#ifndef PURPLE_SQLITE3_H
#define PURPLE_SQLITE3_H

#include <glib.h>
#include <gio/gio.h>

#include "purpleversion.h"

G_BEGIN_DECLS

/**
 * PURPLE_SQLITE3_ERROR:
 *
 * An error domain for sqlite3 errors.
 *
 * Since: 3.0
 */
#define PURPLE_SQLITE3_DOMAIN \
	g_quark_from_static_string("sqlite3") \
	PURPLE_AVAILABLE_MACRO_IN_3_0

/**
 * PurpleSqlite3:
 *
 * A sqlite3 connection.
 *
 * This type alias exists to avoid requiring the sqlite3 header, but is no
 * different from the `sqlite3` type.
 *
 * If that header is included first, this will be exactly equivalent, otherwise
 * it will be a generic `gpointer`, which you should cast to a `sqlite3`.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_TYPE_IN_3_0
#ifdef SQLITE_API
typedef sqlite3 PurpleSqlite3;
#else
typedef gpointer PurpleSqlite3;
#endif

/**
 * purple_sqlite3_get_schema_version:
 * @db: The sqlite3 connection.
 * @error: Return address for a #GError, or %NULL.
 *
 * Attempts to read the result of `PRAGMA user_version` which this API uses to
 * store the schema version.
 *
 * Returns: %TRUE on success, or %FALSE on error with @error set.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
int purple_sqlite3_get_schema_version(PurpleSqlite3 *db, GError **error);

/**
 * purple_sqlite3_run_migrations_from_strings:
 * @db: The sqlite3 connection.
 * @migrations: (array zero-terminated=1): A list of SQL statements, each item
 *              being its own migration.
 * @error: Return address for a #GError, or %NULL.
 *
 * 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.
 *
 * ```c
 * 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.
 *
 * Returns: %TRUE on success, or %FALSE on error potentially with @error set.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_sqlite3_run_migrations_from_strings(PurpleSqlite3 *db, const char *migrations[], GError **error);

/**
 * purple_sqlite3_run_migrations_from_resources:
 * @db: The sqlite3 connection.
 * @path: The base path in @resource to use.
 * @migrations: (array zero-terminated=1): The list of migrations in the order
 *              to run them.
 * @error: Return address for a #GError, or %NULL.
 *
 * Runs the given migrations in the order they are given. The index of each
 * migration plus 1 is assumed 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 will attempt to load the migrations via
 * [func@Gio.resources_open_stream] by concatenating @path and the individual
 * items of @migrations. Each migration will be ran in a transaction that
 * includes updating the schema version, which is stored in
 * `PRAGMA user_version`. This means you can't use `PRAGMA user_version` for
 * other things.
 *
 * Returns: %TRUE on success, or %FALSE on error potentially with @error set.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_sqlite3_run_migrations_from_resources(PurpleSqlite3 *db, const char *path, const char *migrations[], GError **error);

G_END_DECLS

#endif /* PURPLE_SQLITE3_H */