SQL rendering API

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

## Stability Level

Stable, unless otherwise indicated

## Synopsis

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

    struct              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

### struct GdaSqlRenderingContext

    struct GdaSqlRenderingContext {
    	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;
    	GdaSqlRenderingFunc      render_distinct;
    };

Specifies the context in which a GdaSqlStatement is being converted to SQL.

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
GdaSqlRenderingFunc `render_distinct`; | function to render the DISTINCT clause in a SELECT

### 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`. [allow-none]
`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);

Function 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