#include <glib.h>
#include <db-util/sql-generic.h>
#include <db-util/jbson.h>

Data Structures
struct	JThreadVariables
	The JThreadVariables struct bundles the thread-local DB connection, the query cache and the schema cache. More...

struct	JSqlBatch
	Manages the status of a batch. More...

struct	JSqlStatement
	The JSqlStatement wraps a DB backend-specific prepared statement. More...

Macros
#define	BACKEND_ID_TYPE J_DB_TYPE_UINT64
	The ID type that will be sent back to the client.

Typedefs
typedef struct JThreadVariables	JThreadVariables

typedef struct JSqlBatch	JSqlBatch

typedef struct JSqlStatement	JSqlStatement

Functions
	G_LOCK_EXTERN (sql_backend_lock)
	Starting a batch requires locking if the DB backend does not support concurrent accesses.

void	thread_variables_fini (void *ptr)
	Free function for JThreadVariables.

JThreadVariables *	thread_variables_get (gpointer backend_data, GError **error)
	Retrieve the thread-private JThreadVariables.

JSqlStatement *	j_sql_statement_new (gchar const query, GArray types_in, GArray types_out, GHashTable out_variables_index, GHashTable variable_types, GError *error)
	Construct a JSqlStatement struct from the necessary information.

void	j_sql_statement_free (JSqlStatement *ptr)
	Destructor for a JSqlStatement.

GString *	j_sql_get_full_field_name (const gchar namespace, const gchar table, const gchar *field)
	Get the full field name from the different parts.

gboolean	_backend_schema_get (gpointer backend_data, gchar const namespace, gchar const name, bson_t schema, GError *error)
	Retrieve the schema as bson document.

GHashTable *	get_schema (gpointer backend_data, gchar const namespace, gchar const name, GError **error)
	Get the schema as a HashTable for internal usage.

gboolean	build_query_condition_part (gpointer backend_data, JSqlBatch batch, bson_iter_t iter, GString sql, JDBSelectorMode mode, GArray arr_types_in, GHashTable schema, GError *error)
	Build the WHERE part of a SELECT statement from a selector.

gboolean	bind_selector_query (gpointer backend_data, const gchar namespace, bson_iter_t iter, JSqlStatement statement, GHashTable schema, GError **error)
	Bind the variables in the WHERE part of a SELECT statement.

gboolean	_backend_query_ids (gpointer backend_data, gpointer _batch, gchar const name, bson_t const selector, GArray matches, GError error)
	Query the IDs of rows that match a selector.

gboolean	_backend_batch_start (gpointer backend_data, JSqlBatch batch, GError *error)
	Start a batch. Starts a transaction in the DB backend.

gboolean	_backend_batch_execute (gpointer backend_data, JSqlBatch batch, GError *error)
	Execute a batch. Commits a transaction in the DB backend.

gboolean	_backend_batch_abort (gpointer backend_data, JSqlBatch batch, GError *error)
	Abort a batch. Triggers a rollback in the DB backend.

Variables
GPrivate	thread_variables_global
	Holds a thread-private pointer to JThreadVariables.

JSQLSpecifics *	specs
	Contains the specific string constants and functions for a DB backend.

Macro Definition Documentation

◆ BACKEND_ID_TYPE

#define BACKEND_ID_TYPE J_DB_TYPE_UINT64

The ID type that will be sent back to the client.

This library contains bson utility functions and a generic SQL DB backend implementation that must be specialized by providing a JSQLSpecifics struct at init.

Further information can be found in doc/db-code.md.

The implementation of the SQL functions is split into:

Data Definition Language (DDL)
Data Manipulation Language (DML)
Data Query Language (DQL)
Transaction Control Language (TCL)

Attention: Not all DB backends support this type as autoincremented primary key (e.g., SQLite). In this case a type conversion will happen.

Typedef Documentation

◆ JSqlBatch

typedef struct JSqlBatch JSqlBatch

◆ JSqlStatement

typedef struct JSqlStatement JSqlStatement

◆ JThreadVariables

typedef struct JThreadVariables JThreadVariables

Function Documentation

◆ _backend_batch_abort()

gboolean _backend_batch_abort	(	gpointer	backend_data,
		JSqlBatch *	batch,
		GError **	error
	)

Abort a batch. Triggers a rollback in the DB backend.

Parameters

	backend_data	The backend-specific information to open a connection.
	batch	The batch to modify.
[out]	error	An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ _backend_batch_execute()

gboolean _backend_batch_execute	(	gpointer	backend_data,
		JSqlBatch *	batch,
		GError **	error
	)

Execute a batch. Commits a transaction in the DB backend.

Parameters

	backend_data	The backend-specific information to open a connection.
	batch	The batch to modify.
[out]	error	An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ _backend_batch_start()

gboolean _backend_batch_start	(	gpointer	backend_data,
		JSqlBatch *	batch,
		GError **	error
	)

Start a batch. Starts a transaction in the DB backend.

Parameters

	backend_data	The backend-specific information to open a connection.
	batch	The batch to modify.
[out]	error	An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ _backend_query_ids()

gboolean _backend_query_ids	(	gpointer	backend_data,
		gpointer	_batch,
		gchar const *	name,
		bson_t const *	selector,
		GArray **	matches,
		GError **	error
	)

Query the IDs of rows that match a selector.

It is is used in the update and delete functions.

Todo:: Update and delete could be done by adding the selection part to the respective query, making this function unnecessary.

Parameters

	backend_data	The backend-specific information to open a connection.
	_batch	A JSqlBatch object.
	name	The schema name.
	selector	A bson selector document sent by the client.
[out]	matches	A GArray of the matched IDs.
[out]	error	An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

Todo:: check if caching this statement makes any difference with different databases

◆ _backend_schema_get()

gboolean _backend_schema_get	(	gpointer	backend_data,
		gchar const *	namespace,
		gchar const *	name,
		bson_t *	schema,
		GError **	error
	)

Retrieve the schema as bson document.

This format is suitable for answering schema requests by clients.

Parameters

	backend_data	The backend-specific information to open a connection.
	namespace	The namespace of the schema.
	name	The schema name.
[in,out]	schema	A bson document to be filled with schema information as a list of variable name and type pairs.
[out]	error	An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ bind_selector_query()

gboolean bind_selector_query	(	gpointer	backend_data,
		const gchar *	namespace,
		bson_iter_t *	iter,
		JSqlStatement *	statement,
		GHashTable *	schema,
		GError **	error
	)

Bind the variables in the WHERE part of a SELECT statement.

Parameters

backend_data	The backend-specific information to open a connection.
iter	An initialized iterator over the relevant part of the selector bson document. Should be retrieved the same way as for build_selector_query to ensure the same order of variables!
statement	A JSqlStatement which
schema	The database schema in hash table format.

Todo:: need to change this one for joins

Parameters

[out] error An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ build_query_condition_part()

gboolean build_query_condition_part	(	gpointer	backend_data,
		JSqlBatch *	batch,
		bson_iter_t *	iter,
		GString *	sql,
		JDBSelectorMode	mode,
		GArray *	arr_types_in,
		GHashTable *	schema,
		GError **	error
	)

Build the WHERE part of a SELECT statement from a selector.

Parameters

	backend_data	The backend-specific information to open a connection.
	iter	An initialized iterator over the relevant part of the selector bson document.
	batch	The batch of the operation.
[in,out]	sql	A GString to which the WHERE part of the query should be appended.
	mode	The mode of the selector (i.e., AND or OR).
	arr_types_in	An allocated GArray to which the found types will be appended.
	schema	The database schema in hash table format.

Todo:: need to change this one for joins

Parameters

[out] error An uninitialized GError* for error code passing.

Returns: gboolean TRUE on success, FALSE otherwise.

◆ G_LOCK_EXTERN()

G_LOCK_EXTERN ( sql_backend_lock )

Starting a batch requires locking if the DB backend does not support concurrent accesses.

◆ get_schema()

GHashTable * get_schema	(	gpointer	backend_data,
		gchar const *	namespace,
		gchar const *	name,
		GError **	error
	)

Get the schema as a HashTable for internal usage.

Uses a transparent cache for schemas.

Todo:: Currently _backend_schema_get is called and the returned bson is converted to a GHashTable. A better way would be to use one common function for both so no conversion is neccessary.

Parameters

	backend_data	The backend-specific information to open a connection if needed.
	namespace	The namespace of the schema.
	name	The schema name.
[out]	error	An uninitialized GError* for error code passing.

Returns: GHashTable* A valid GHashTable pointer on success or NULL otherwise. The hash table should by freed using g_hash_table_unref (or by using g_autoptr).

◆ j_sql_get_full_field_name()

GString * j_sql_get_full_field_name	(	const gchar *	namespace,
		const gchar *	table,
		const gchar *	field
	)

Get the full field name from the different parts.

The name is correctly quoted and suitable as key in schema hash tables and as name in queries.

Parameters

namespace	The namespace of the operation.
table	The name of the table.
field	The name of a column in the table.

Returns: GString*

◆ j_sql_statement_free()

void j_sql_statement_free ( JSqlStatement * ptr )

Destructor for a JSqlStatement.

Parameters

ptr	Pointer to the Statement.

◆ j_sql_statement_new()

JSqlStatement * j_sql_statement_new	(	gchar const *	query,
		GArray *	types_in,
		GArray *	types_out,
		GHashTable *	out_variables_index,
		GHashTable *	variable_types,
		GError **	error
	)

Construct a JSqlStatement struct from the necessary information.

Parameters

	query	A SQL query string.
	types_in	The types of input variables in correct order. Needed by some DB backends for statement compilation.
	types_out	The types of output variables in correct order. Needed by some DB backends for statement compilation.
	out_variables_index	A map from output variable names to their position. See JSqlStatement for details.
	variable_types	Type information for the query. See JSqlStatement for details.
[out]	error	An uninitialized GError* for error code passing.

Returns: JSqlStatement* The constructed statement or NULL on error.

Attention: If the function returns a valid pointer in_variables_index and out_variables_index are now owned by the new struct and the original pointers are set to NULL.

◆ thread_variables_fini()

void thread_variables_fini ( void * ptr )

Free function for JThreadVariables.

Parameters

ptr	Pointer to an allocated JThreadVariables struct.

◆ thread_variables_get()

JThreadVariables * thread_variables_get	(	gpointer	backend_data,
		GError **	error
	)

Retrieve the thread-private JThreadVariables.

The struct will be initialized if this function is called by a new thread for the first time.

Parameters

	backend_data	The backend-specific information to open a connection.
[out]	error	An uninitialized GError* for error code passing.

Returns: JThreadVariables* An initilized pointer to the thred-pribvate variables. The returned data schould NOT be freed.

Variable Documentation

◆ specs

JSQLSpecifics* specs

extern

Contains the specific string constants and functions for a DB backend.

◆ thread_variables_global

GPrivate thread_variables_global

extern

Holds a thread-private pointer to JThreadVariables.

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

◆ BACKEND_ID_TYPE

Typedef Documentation

◆ JSqlBatch

◆ JSqlStatement

◆ JThreadVariables

Function Documentation

◆ _backend_batch_abort()

◆ _backend_batch_execute()

◆ _backend_batch_start()

◆ _backend_query_ids()

◆ _backend_schema_get()

◆ bind_selector_query()

◆ build_query_condition_part()

◆ G_LOCK_EXTERN()

◆ get_schema()

◆ j_sql_get_full_field_name()

◆ j_sql_statement_free()

◆ j_sql_statement_new()

◆ thread_variables_fini()

◆ thread_variables_get()

Variable Documentation

◆ specs

◆ thread_variables_global