SQL rendering API

SQL rendering API — Adapting the SQL to the database's own SQL dialect

Synopsis

#include <libgda/gda-statement-extra.h>

                    GdaSqlRenderingContext;
gchar *             (*GdaSqlRenderingValue)             (const GValue *value,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);
gchar *             (*GdaSqlRenderingPSpecFunc)         (GdaSqlParamSpec *pspec,
                                                         GdaSqlExpr *expr,
                                                         GdaSqlRenderingContext *context,
                                                         gboolean *is_default,
                                                         gboolean *is_null,
                                                         GError **error);
gchar *             (*GdaSqlRenderingExpr)              (GdaSqlExpr *expr,
                                                         GdaSqlRenderingContext *context,
                                                         gboolean *is_default,
                                                         gboolean *is_null,
                                                         GError **error);
gchar *             (*GdaSqlRenderingFunc)              (GdaSqlAnyPart *node,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);
gchar *             gda_statement_to_sql_real           (GdaStatement *stmt,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);

Description

Libgda is able to render a GdaStatement statement to SQL in a generic way (as close as possible to the SQL standard). However as each database has ultimately its own SQL dialect, some parts of the rendering has to be specialized.

Customization is achieved by providing custom implementations of SQL rendering functions for each kind of part in a GdaSqlStatement structure, all packed in a GdaSqlRenderingContext context structure. Functions which are not customized will be implemented by the default ones.

Details

GdaSqlRenderingContext

typedef struct {
	GdaStatementSqlFlag      flags;
	GdaSet                  *params;
	GSList                  *params_used;
	GdaServerProvider       *provider; /* may be NULL */
	GdaConnection           *cnc;      /* may be NULL */

	/* rendering functions */
	GdaSqlRenderingValue     render_value;
	GdaSqlRenderingPSpecFunc render_param_spec; 
	GdaSqlRenderingExpr      render_expr;

	GdaSqlRenderingFunc      render_unknown;

	GdaSqlRenderingFunc      render_begin;
	GdaSqlRenderingFunc      render_rollback;
	GdaSqlRenderingFunc      render_commit;
	GdaSqlRenderingFunc      render_savepoint;
	GdaSqlRenderingFunc      render_rollback_savepoint;
	GdaSqlRenderingFunc      render_delete_savepoint;

	GdaSqlRenderingFunc      render_select;
	GdaSqlRenderingFunc      render_insert;
	GdaSqlRenderingFunc      render_delete;
	GdaSqlRenderingFunc      render_update;
	GdaSqlRenderingFunc      render_compound;

	GdaSqlRenderingFunc      render_field;
	GdaSqlRenderingFunc      render_table;
	GdaSqlRenderingFunc      render_function;
	GdaSqlRenderingFunc      render_operation;
	GdaSqlRenderingFunc      render_case;
	GdaSqlRenderingFunc      render_select_field;
	GdaSqlRenderingFunc      render_select_target;
	GdaSqlRenderingFunc      render_select_join;
	GdaSqlRenderingFunc      render_select_from;
	GdaSqlRenderingFunc      render_select_order;

	/* Padding for future expansion */
	void (*_gda_reserved1) (void);
	void (*_gda_reserved2) (void);
	void (*_gda_reserved3) (void);
	void (*_gda_reserved4) (void);
	void (*_gda_reserved5) (void);
	void (*_gda_reserved6) (void);
	void (*_gda_reserved7) (void);
	void (*_gda_reserved8) (void);
} GdaSqlRenderingContext;

Structure to wrap all the individual part's SQL rendering functions

GdaStatementSqlFlag flags;

Global rendering options

GdaSet *params;

Parameters to be used while doing the rendering

GSList *params_used;

When rendering is complete, contains the ordered list of parameters which have been used while doing the rendering

GdaServerProvider *provider;

Pointer to the server provider to be used

GdaConnection *cnc;

Pointer to the connection to be used

GdaSqlRenderingValue render_value;

function to render a GValue

GdaSqlRenderingPSpecFunc render_param_spec;

function to render a GdaSqlParamSpec

GdaSqlRenderingExpr render_expr;

function to render a GdaSqlExpr

GdaSqlRenderingFunc render_unknown;

function to render a GdaSqlStatementUnknown

GdaSqlRenderingFunc render_begin;

function to render a BEGIN GdaSqlStatementTransaction

GdaSqlRenderingFunc render_rollback;

function to render a ROLLBACK GdaSqlStatementTransaction

GdaSqlRenderingFunc render_commit;

function to render a COMMIT GdaSqlStatementTransaction

GdaSqlRenderingFunc render_savepoint;

function to render a ADD SAVEPOINT GdaSqlStatementTransaction

GdaSqlRenderingFunc render_rollback_savepoint;

function to render a ROLBACK SAVEPOINT GdaSqlStatementTransaction

GdaSqlRenderingFunc render_delete_savepoint;

function to render a DELETE SAVEPOINT GdaSqlStatementTransaction

GdaSqlRenderingFunc render_select;

function to render a GdaSqlStatementSelect

GdaSqlRenderingFunc render_insert;

function to render a GdaSqlStatementInsert

GdaSqlRenderingFunc render_delete;

function to render a GdaSqlStatementDelete

GdaSqlRenderingFunc render_update;

function to render a GdaSqlStatementUpdate

GdaSqlRenderingFunc render_compound;

function to render a GdaSqlStatementCompound

GdaSqlRenderingFunc render_field;

function to render a GdaSqlField

GdaSqlRenderingFunc render_table;

function to render a GdaSqlTable

GdaSqlRenderingFunc render_function;

function to render a GdaSqlFunction

GdaSqlRenderingFunc render_operation;

function to render a GdaSqlOperation

GdaSqlRenderingFunc render_case;

function to render a GdaSqlCase

GdaSqlRenderingFunc render_select_field;

function to render a GdaSqlSelectField

GdaSqlRenderingFunc render_select_target;

function to render a GdaSqlSelectTarget

GdaSqlRenderingFunc render_select_join;

function to render a GdaSqlSelectJoin

GdaSqlRenderingFunc render_select_from;

function to render a GdaSqlSelectFrom

GdaSqlRenderingFunc render_select_order;

function to render a GdaSqlSelectOrder

_gda_reserved1 ()

_gda_reserved2 ()

_gda_reserved3 ()

_gda_reserved4 ()

_gda_reserved5 ()

_gda_reserved6 ()

_gda_reserved7 ()

_gda_reserved8 ()


GdaSqlRenderingValue ()

gchar *             (*GdaSqlRenderingValue)             (const GValue *value,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);

Rendering function type to render a GValue

value :

the GValue to render

context :

the rendering context

error :

a place to store errors, or NULL

Returns :

a new string, or NULL if an error occurred

GdaSqlRenderingPSpecFunc ()

gchar *             (*GdaSqlRenderingPSpecFunc)         (GdaSqlParamSpec *pspec,
                                                         GdaSqlExpr *expr,
                                                         GdaSqlRenderingContext *context,
                                                         gboolean *is_default,
                                                         gboolean *is_null,
                                                         GError **error);

Rendering function type to render a GdaSqlParamSpec

pspec :

GdaSqlParamSpec to render

expr :

GdaSqlExpr which may hold the default value for the parameter, or NULL

context :

the rendering context

is_default :

pointer to a gboolean which is set to TRUE if value should be considered as a default value

is_null :

pointer to a gboolean which is set to TRUE if value should be considered as NULL

error :

a place to store errors, or NULL

Returns :

a new string, or NULL if an error occurred

GdaSqlRenderingExpr ()

gchar *             (*GdaSqlRenderingExpr)              (GdaSqlExpr *expr,
                                                         GdaSqlRenderingContext *context,
                                                         gboolean *is_default,
                                                         gboolean *is_null,
                                                         GError **error);

Rendering function type to render a GdaSqlExpr

expr :

GdaSqlExpr to render

context :

the rendering context

is_default :

pointer to a gboolean which is set to TRUE if value should be considered as a default value

is_null :

pointer to a gboolean which is set to TRUE if value should be considered as NULL

error :

a place to store errors, or NULL

Returns :

a new string, or NULL if an error occurred

GdaSqlRenderingFunc ()

gchar *             (*GdaSqlRenderingFunc)              (GdaSqlAnyPart *node,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);

Rendering function type to render any GdaSqlAnyPart

node :

a GdaSqlAnyPart pointer, to be cast to the correct type depending on which part the function has to render

context :

the rendering context

error :

a place to store errors, or NULL

Returns :

a new string, or NULL if an error occurred

gda_statement_to_sql_real ()

gchar *             gda_statement_to_sql_real           (GdaStatement *stmt,
                                                         GdaSqlRenderingContext *context,
                                                         GError **error);

Renders stmt to its SQL representation, using context to specify how each part of stmt must be rendered. This function is mainly used by database provider's implementations which require to specialize some aspects of SQL rendering to be adapted to the database,'s own SQL dialect (for example SQLite rewrites the 'FALSE' and 'TRUE' literals as '0' and 'NOT 0').

stmt :

a GdaStatement object

context :

a GdaSqlRenderingContext context

error :

a place to store errors, or NULL

Returns :

a new string, or NULL if an error occurred

See Also

gda_statement_to_sql_extended()