Generic SQL interface. More...

#include "sql.h"
#include <assert.h>
#include <errno.h>
#include <stdlib.h>
#include <string.h>

Macros
#define	G_LOG_DOMAIN "md manage"
	GLib log domain.

Functions
int	sql_prepare_internal (int, int, const char , va_list, sql_stmt_t *)
	Prepare a statement. More...

int	sql_exec_internal (int, sql_stmt_t *)
	Execute a prepared statement. More...

int	sql_explain_internal (const char *, va_list)
	Write debug messages with the query plan for an SQL query to the log. More...

gchar *	sql_nquote (const char *string, size_t length)
	Quotes a string of a known length to be passed to sql statements. More...

gchar *	sql_quote (const char *string)
	Quotes a string to be passed to sql statements. More...

gchar *	sql_insert (const char *string)
	Get the SQL insert expression for a string. More...

int	sqlv (int retry, char *sql, va_list args)
	Perform an SQL statement. More...

void	sql (char *sql,...)
	Perform an SQL statement, retrying if database is busy or locked. More...

int	sql_error (char *sql,...)
	Perform an SQL statement, retrying if database is busy or locked. More...

int	sql_giveup (char *sql,...)
	Perform an SQL statement, giving up if database is busy or locked. More...

static int	sql_x_internal (int log, char sql, va_list args, sql_stmt_t *stmt_return)
	Get a particular cell from a SQL query. More...

int	sql_x (char sql, va_list args, sql_stmt_t *stmt_return)
	Get a particular cell from a SQL query. More...

double	sql_double (char *sql,...)
	Get the first value from a SQL query, as a double. More...

int	sql_int (char *sql,...)
	Get a particular cell from a SQL query, as an int. More...

char *	sql_string (char *sql,...)
	Get a particular cell from a SQL query, as an string. More...

int	sql_int64 (long long int ret, char sql,...)
	Get a particular cell from a SQL query, as an int64. More...

long long int	sql_int64_0 (char *sql,...)
	Get a first column of first row from a SQL query, as an int64. More...

int	sql_explain (const char *sql,...)
	Write debug messages with the query plan for an SQL query to the log. More...

void	init_prepared_iterator (iterator_t iterator, sql_stmt_t stmt)
	Initialise an iterator. More...

void	init_iterator (iterator_t iterator, const char sql,...)
	Initialise an iterator. More...

double	iterator_double (iterator_t *iterator, int col)
	Get a double column from an iterator. More...

int	iterator_int (iterator_t *iterator, int col)
	Get a int column from an iterator. More...

long long int	iterator_int64 (iterator_t *iterator, int col)
	Get an integer column from an iterator. More...

const char *	iterator_string (iterator_t *iterator, int col)
	Get a string column from an iterator. More...

void	cleanup_iterator (iterator_t *iterator)
	Cleanup an iterator. More...

gboolean	next (iterator_t *iterator)
	Increment an iterator. More...

sql_stmt_t *	sql_prepare (const char *sql,...)
	Prepare a statement. More...

int	sql_exec (sql_stmt_t *stmt)
	Execute a prepared statement. More...

Variables
int	log_errors = 1
	Whether to log errors. More...

Detailed Description

Generic SQL interface.

This is a small generic interface for SQL database access.

To add support for a specific database, like Postgres, a few functions (for example, sql_prepare_internal and sql_exec_internal) need to be implemented for that database.

Function Documentation

◆ cleanup_iterator()

void cleanup_iterator ( iterator_t * iterator )

Cleanup an iterator.

Parameters

[in] iterator Iterator.

◆ init_iterator()

void init_iterator	(	iterator_t *	iterator,
		const char *	sql,
			...
	)

Initialise an iterator.

Parameters

[in]	iterator	Iterator.
[in]	sql	Format string for SQL.

◆ init_prepared_iterator()

void init_prepared_iterator	(	iterator_t *	iterator,
		sql_stmt_t *	stmt
	)

Initialise an iterator.

Parameters

[in]	iterator	Iterator.
[in]	stmt	Statement.

◆ iterator_double()

double iterator_double	(	iterator_t *	iterator,
		int	col
	)

Get a double column from an iterator.

Parameters

[in]	iterator	Iterator.
[in]	col	Column offset.

Returns: Value of given column.

◆ iterator_int()

int iterator_int	(	iterator_t *	iterator,
		int	col
	)

Get a int column from an iterator.

Parameters

[in]	iterator	Iterator.
[in]	col	Column offset.

Returns: Value of given column.

◆ iterator_int64()

long long int iterator_int64	(	iterator_t *	iterator,
		int	col
	)

Get an integer column from an iterator.

Parameters

[in]	iterator	Iterator.
[in]	col	Column offset.

Returns: Value of given column.

◆ iterator_string()

const char* iterator_string	(	iterator_t *	iterator,
		int	col
	)

Get a string column from an iterator.

Parameters

[in]	iterator	Iterator.
[in]	col	Column offset.

Returns: Value of given column.

◆ next()

gboolean next ( iterator_t * iterator )

Increment an iterator.

Parameters

[in] iterator Iterator.

Returns: TRUE if there was a next item, else FALSE.

◆ sql()

void sql	(	char *	sql,
			...
	)

Perform an SQL statement, retrying if database is busy or locked.

Parameters

[in]	sql	Format string for SQL statement.
[in]	...	Arguments for format string.

◆ sql_double()

double sql_double	(	char *	sql,
			...
	)

Get the first value from a SQL query, as a double.

Warning: Aborts on invalid queries.; Aborts when the query returns fewer rows than row. The caller must ensure that the query will return sufficient rows.

Parameters

[in]	sql	Format string for SQL query.
[in]	...	Arguments for format string.

Returns: Result of the query as an integer.

◆ sql_error()

int sql_error	(	char *	sql,
			...
	)

Perform an SQL statement, retrying if database is busy or locked.

Return on error, instead of aborting.

Parameters

[in]	sql	Format string for SQL statement.
[in]	...	Arguments for format string.

Returns: 0 success, 2 reserved (lock unavailable), 3 unique constraint violation, -1 error.

◆ sql_exec()

int sql_exec ( sql_stmt_t * stmt )

Execute a prepared statement.

Parameters

[in] stmt Statement.

Returns: 0 complete, 1 row available in results, 2 rerun prepare, -1 error, -2 gave up with statement reset.

◆ sql_exec_internal()

int sql_exec_internal	(	int	retry,
		sql_stmt_t *	stmt
	)

Execute a prepared statement.

Parameters

[in]	retry	Whether to keep retrying while database is busy or locked.
[in]	stmt	Statement.

Returns: 0 complete, 1 row available in results, -1 error, -2 gave up, -3 lock unavailable, -4 unique constraint violation.

◆ sql_explain()

int sql_explain	(	const char *	sql,
			...
	)

Write debug messages with the query plan for an SQL query to the log.

Parameters

[in]	sql	Format string for the SQL query.
[in]	...	Format string arguments.

Returns: 0 success, -1 error.

◆ sql_explain_internal()

int sql_explain_internal	(	const char *	sql,
		va_list	args
	)

Write debug messages with the query plan for an SQL query to the log.

Parameters

[in]	sql	Format string for the SQL query.
[in]	args	Format string arguments in a va_list.

Returns: 0 success, -1 error.

◆ sql_giveup()

int sql_giveup	(	char *	sql,
			...
	)

Perform an SQL statement, giving up if database is busy or locked.

Parameters

[in]	sql	Format string for SQL statement.
[in]	...	Arguments for format string.

Returns: 0 success, 1 gave up, 2 reserved (lock unavailable), 3 unique constraint violation, -1 error.

◆ sql_insert()

gchar* sql_insert ( const char * string )

Get the SQL insert expression for a string.

Parameters

[in] string The string, which may be NULL.

Returns: Freshly allocated expression suitable for an INSERT statement, including SQL quotation marks.

◆ sql_int()

int sql_int	(	char *	sql,
			...
	)

Get a particular cell from a SQL query, as an int.

Warning: Aborts on invalid queries.; Aborts when the query returns fewer rows than row. The caller must ensure that the query will return sufficient rows.

Parameters

[in]	sql	Format string for SQL query.
[in]	...	Arguments for format string.

Returns: Result of the query as an integer.

◆ sql_int64()

int sql_int64	(	long long int *	ret,
		char *	sql,
			...
	)

Get a particular cell from a SQL query, as an int64.

Parameters

[in]	ret	Return value.
[in]	sql	Format string for SQL query.
[in]	...	Arguments for format string.

Returns: 0 success, 1 too few rows, -1 error.

◆ sql_int64_0()

long long int sql_int64_0	(	char *	sql,
			...
	)

Get a first column of first row from a SQL query, as an int64.

Return 0 on error.

Parameters

[in]	sql	Format string for SQL query.
[in]	...	Arguments for format string.

Returns: 0 success, 1 too few rows, -1 error.

◆ sql_nquote()

gchar* sql_nquote	(	const char *	string,
		size_t	length
	)

Quotes a string of a known length to be passed to sql statements.

Parameters

[in]	string	String to quote.
[in]	length	Size of `string`.

Returns: Freshly allocated, quoted string. Free with g_free.

◆ sql_prepare()

sql_stmt_t* sql_prepare	(	const char *	sql,
			...
	)

Prepare a statement.

Parameters

[in] sql Format string for SQL.

Returns: Statement on success, NULL on error.

◆ sql_prepare_internal()

int sql_prepare_internal	(	int	retry,
		int	log,
		const char *	sql,
		va_list	args,
		sql_stmt_t **	stmt
	)

Prepare a statement.

Parameters

[in]	retry	Whether to keep retrying while database is busy or locked.
[in]	log	Whether to keep retrying while database is busy or locked.
[in]	sql	Format string for SQL statement.
[in]	args	Arguments for format string.
[out]	stmt	Statement return.

Returns: 0 success, 1 gave up, -1 error.

◆ sql_quote()

gchar* sql_quote ( const char * string )

Quotes a string to be passed to sql statements.

Parameters

[in] string String to quote, has to be \0 terminated.

Returns: Freshly allocated, quoted string. Free with g_free.

◆ sql_string()

char* sql_string	(	char *	sql,
			...
	)

Get a particular cell from a SQL query, as an string.

Parameters

[in]	sql	Format string for SQL query.
[in]	...	Arguments for format string.

Returns: Freshly allocated string containing the result, NULL otherwise. NULL means that either the selected value was NULL or there were no rows in the result.

◆ sql_x()

int sql_x	(	char *	sql,
		va_list	args,
		sql_stmt_t **	stmt_return
	)

Get a particular cell from a SQL query.

Do logging as usual.

Parameters

[in]	sql	Format string for SQL query.
[in]	args	Arguments for format string.
[out]	stmt_return	Return from statement.

Returns: 0 success, 1 too few rows, -1 error.

◆ sql_x_internal()

static int sql_x_internal	(	int	log,
		char *	sql,
		va_list	args,
		sql_stmt_t **	stmt_return
	)

static

Get a particular cell from a SQL query.

Parameters

[in]	log	Whether to do g_debug logging.
[in]	sql	Format string for SQL query.
[in]	args	Arguments for format string.
[out]	stmt_return	Return from statement.

Returns: 0 success, 1 too few rows, -1 error.

◆ sqlv()

int sqlv	(	int	retry,
		char *	sql,
		va_list	args
	)

Perform an SQL statement.

Parameters

[in]	retry	Whether to keep retrying while database is busy or locked.
[in]	sql	Format string for SQL statement.
[in]	args	Arguments for format string.

Returns: 0 success, 1 gave up (even when retry given), 2 reserved (lock unavailable), 3 unique constraint violation, -1 error.

Variable Documentation

◆ log_errors

int log_errors = 1

Whether to log errors.

Used to turn off logging when cancelling statements on exit.

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ cleanup_iterator()

◆ init_iterator()

◆ init_prepared_iterator()

◆ iterator_double()

◆ iterator_int()

◆ iterator_int64()

◆ iterator_string()

◆ next()

◆ sql()

◆ sql_double()

◆ sql_error()

◆ sql_exec()

◆ sql_exec_internal()

◆ sql_explain()

◆ sql_explain_internal()

◆ sql_giveup()

◆ sql_insert()

◆ sql_int()

◆ sql_int64()

◆ sql_int64_0()

◆ sql_nquote()

◆ sql_prepare()

◆ sql_prepare_internal()

◆ sql_quote()

◆ sql_string()

◆ sql_x()

◆ sql_x_internal()

◆ sqlv()

Variable Documentation

◆ log_errors