GdaSqlParser

GdaSqlParser

Synopsis

#include <sql-parser/gda-sql-parser.h>

                    GdaSqlParser;
enum                GdaSqlParserMode;
GdaSqlParser *      gda_sql_parser_new                  (void);
GdaStatement *      gda_sql_parser_parse_string         (GdaSqlParser *parser,
                                                         const gchar *sql,
                                                         const gchar **remain,
                                                         GError **error);
GdaBatch *          gda_sql_parser_parse_string_as_batch
                                                        (GdaSqlParser *parser,
                                                         const gchar *sql,
                                                         const gchar **remain,
                                                         GError **error);
GdaBatch *          gda_sql_parser_parse_file_as_batch  (GdaSqlParser *parser,
                                                         const gchar *filename,
                                                         GError **error);

gchar *             gda_sql_identifier_quote            (const gchar *id,
                                                         GdaConnection *cnc,
                                                         GdaServerProvider *prov,
                                                         gboolean meta_store_convention,
                                                         gboolean force_quotes);
gchar **            gda_sql_identifier_split            (const gchar *id);

Object Hierarchy

  GObject
   +----GdaSqlParser

Implemented Interfaces

GdaSqlParser implements GdaLockable.

Properties

  "column-error"             gint                  : Read
  "debug"                    gboolean              : Write
  "line-error"               gint                  : Read
  "mode"                     gint                  : Read / Write
  "tokenizer-flavour"        gint                  : Read / Write

Description

Details

GdaSqlParser

typedef struct _GdaSqlParser GdaSqlParser;


enum GdaSqlParserMode

typedef enum {
        GDA_SQL_PARSER_MODE_PARSE,
        GDA_SQL_PARSER_MODE_DELIMIT
} GdaSqlParserMode;


gda_sql_parser_new ()

GdaSqlParser *      gda_sql_parser_new                  (void);

Creates a new GdaSqlParser object

Returns :

the new object

gda_sql_parser_parse_string ()

GdaStatement *      gda_sql_parser_parse_string         (GdaSqlParser *parser,
                                                         const gchar *sql,
                                                         const gchar **remain,
                                                         GError **error);

Parses sql and creates a GdaStatement statement from the first SQL statement contained in sql: if sql contains more than one statement, then the remaining part of the string is not parsed at all, and remain (if not NULL) will point at the first non parsed character.

To include variables in the sql string, see the GdaSqlParser's object description.

parser :

a GdaSqlParser object

sql :

the SQL string to parse

remain :

location to store a pointer to remaining part of sql in case sql has multiple statement, or NULL. [out][allow-none]

error :

location to store error, or NULL

Returns :

a new GdaStatement object, or NULL if an error occurred. [transfer full][allow-none]

gda_sql_parser_parse_string_as_batch ()

GdaBatch *          gda_sql_parser_parse_string_as_batch
                                                        (GdaSqlParser *parser,
                                                         const gchar *sql,
                                                         const gchar **remain,
                                                         GError **error);

Parse sql and creates a GdaBatch object which contains all the GdaStatement objects created while parsing (one object per SQL statement). Empty statements (composed of spaces only) do not appear in the resulting object.

sql is parsed and GdaStatement objects are created as long as no error is found in sql. If an error is found at some point, then the parsing stops and remain may contain a non NULL pointer, error may be set, and NULL is returned.

if sql is NULL, then the returned GdaBatch object will contain no statement.

To include variables in the sql string, see the GdaSqlParser's object description.

parser :

a GdaSqlParser object

sql :

the SQL string to parse

remain :

location to store a pointer to remaining part of sql in case an error occurred while parsing sql, or NULL. [out][allow-none]

error :

location to store error, or NULL

Returns :

a new GdaBatch object, or NULL if an error occurred. [transfer full][allow-none]

gda_sql_parser_parse_file_as_batch ()

GdaBatch *          gda_sql_parser_parse_file_as_batch  (GdaSqlParser *parser,
                                                         const gchar *filename,
                                                         GError **error);

Parse filename's contents and creates a GdaBatch object which contains all the GdaStatement objects created while parsing (one object per SQL statement).

filename's contents are parsed and GdaStatement objects are created as long as no error is found. If an error is found at some point, then the parsing stops, error may be set and NULL is returned

if sql is NULL, then the returned GdaBatch object will contain no statement.

parser :

a GdaSqlParser object

filename :

name of the file to parse

error :

location to store error, or NULL

Returns :

a new GdaBatch object, or NULL if an error occurred. [transfer full][allow-none]

gda_sql_identifier_quote ()

gchar *             gda_sql_identifier_quote            (const gchar *id,
                                                         GdaConnection *cnc,
                                                         GdaServerProvider *prov,
                                                         gboolean meta_store_convention,
                                                         gboolean force_quotes);

Use this function for any SQL identifier to make sure that:

  • it is correctly formatted to be used with cnc (if cnc is NULL, then some default SQL quoting rules will be applied, similar to PostgreSQL's way) if for_meta_store is FALSE;

  • it is correctly formatted to be used with the GdaMetaStore's object associated to cnc is for_meta_store is TRUE.

The force_quotes allow some control of how to interpret id: if FALSE, then id will be left unchanged most of the time (except for example if it's a reserved keyword), otherwise if force_quotes is TRUE, then the returned string will most probably have quotes around it to request that the database keep the case sensitiveness (but again, this may vary depending on the database being accessed through cnc).

For example, the following table gives the result of this function depending on the arguments when cnc is NULL (and prov is also NULL):

Table 3. 

id for_meta_store=FALSE, force_quotes=FALSE for_meta_store=TRUE, force_quotes=FALSE for_meta_store=FALSE, force_quotes=TRUE for_meta_store=TRUE, force_quotes=TRUE remark
"double word" "double word" "double word" "double word" "double word" non allowed character in SQL identifier
"CapitalTest" "CapitalTest" "CapitalTest" "CapitalTest" "CapitalTest" Mixed case SQL identifier, already quoted
CapitalTest CapitalTest capitaltest "CapitalTest" "CapitalTest" Mixed case SQL identifier, non quoted
"mytable" "mytable" mytable "mytable" mytable All lowser case, quoted
mytable mytable mytable "mytable" mytable All lowser case
MYTABLE MYTABLE mytable "MYTABLE" "MYTABLE" All upper case
"MYTABLE" "MYTABLE" "MYTABLE" "MYTABLE" "MYTABLE" All upper case, quoted
desc "desc" "desc" "desc" "desc" SQL reserved keyword
5ive "5ive" "5ive" "5ive" "5ive" SQL identifier starting with a digit


Here are a few examples of when and how to use this function:

  • When creating a table, the user has entered the table name, this function can be used to create a valid SQL identifier from the user provided table name:

    gchar *user_sqlid=...
    gchar *valid_sqlid = gda_sql_identifier_quote (user_sqlid, cnc, NULL, FALSE, FALSE);
    gchar *sql = g_strdup_printf ("CREATE TABLE %s ...", valid_sqlid);
    g_free (valid_sqlid);
          

    Note that this is an illustration and creating a table should be sone using a GdaServerOperation object.

  • When updating the meta data associated to a table which has been created with the code above:

    GValue table_name_value = { 0 };
    gchar* column_names[] = { (gchar*)"table_name" };
    GValue* column_values[] = { &table_name_value };
    GdaMetaContext mcontext = { (gchar*)"_tables", 1, column_names, column_values };
    g_value_init (&table_name_value, G_TYPE_STRING);
    g_value_take_string (&table_name_value, gda_sql_identifier_quote (user_sqlid, cnc, NULL, TRUE, FALSE);
    gda_connection_update_meta_store (cnc, &mcontext, NULL);
    g_value_reset (&table_name_value);
          

  • When using a GdaMetaStruct object to fetch information about a table (which has been created with the code above):

    GValue table_name_value = { 0 };
    g_value_init (&table_name_value, G_TYPE_STRING);
    g_value_take_string (&table_name_value, gda_sql_identifier_quote (user_sqlid, cnc, NULL, TRUE, FALSE);
    GdaMetaDbObject *dbo;
    dbo = gda_meta_struct_complement (mstruct, GDA_META_DB_TABLE, NULL, NULL, &table_name_value, NULL);
    g_value_reset (&table_name_value);
          

Note that id must not be a composed SQL identifier (such as "mytable.mycolumn" which should be treated as the "mytable" and "mycolumn" SQL identifiers). If unsure, use gda_sql_identifier_split().

Also note that if cnc is NULL, then it's possible to pass an non NULL prov to have a result specific to prov.

For more information, see the SQL identifiers and abstraction and SQL identifiers in meta data sections.

id :

an SQL identifier

cnc :

a GdaConnection object, or NULL

prov :

a GdaServerProvider object, or NULL for_meta_store set to TRUE if the returned string will be used in a GdaMetaStore

force_quotes :

set to TRUE to force the returned string to be quoted

Returns :

the representation of id ready to be used in SQL statement, as a new string, or NULL if id is in a wrong format

Since 4.0.3


gda_sql_identifier_split ()

gchar **            gda_sql_identifier_split            (const gchar *id);

Splits id into an array of it sub parts. id's format has to be "<part>[.<part>[...]]" where each part is either a text surrounded by double quotes which can contain upper and lower cases or an SQL identifier in lower case.

For example the "test.\"ATable\"" string will result in the array: {"test", "\"ATable\"", NULL}

id :

an SQL identifier

Returns :

a new NULL-terminated array of strings, or NULL (use g_strfreev() to free the returned array). [transfer full][array zero-terminated=1][allow-none]

Property Details

The "column-error" property

  "column-error"             gint                  : Read

Allowed values: >= 0

Default value: 0


The "debug" property

  "debug"                    gboolean              : Write

Default value: FALSE


The "line-error" property

  "line-error"               gint                  : Read

Allowed values: >= 0

Default value: 0


The "mode" property

  "mode"                     gint                  : Read / Write

Allowed values: [0,1]

Default value: 0


The "tokenizer-flavour" property

  "tokenizer-flavour"        gint                  : Read / Write

Allowed values: [0,4]

Default value: 0