Query Functions¶
Introduction¶
This section outlines the query and result functions
Structs¶
-
drizzle_query_st
¶ The internal query object struct
-
drizzle_result_st
¶ The internal result object struct
-
drizzle_column_st
¶ The internal column object struct
Functions¶
-
drizzle_return_t
drizzle_set_ssl
(drizzle_st *con, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)¶ Sets the SSL data
Parameters: - con – A connection object
- key – The path to a key file
- cert – The path to a certificate file
- ca – The path to a certificate authority file
- capath – The path to a directory that contains trusted CA certificate files
- cipher – A list of allowed ciphers for SSL encryption
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_result_st*
drizzle_query
(drizzle_st *con, const char *query, size_t size, drizzle_return_t *ret_ptr)¶ Executes a query and returns a newly allocated result struct
Parameters: - con – A connection object
- query – The query to execute
- size – The length of the query string, if set to 0 then
strlen()
is used to calculate the length - ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: A newly allocated result object
-
ssize_t
drizzle_escape_string
(drizzle_st *con, char **to, const const char *from, const size_t from_size)¶ Escape a string for an SQL query. The
to
parameter is allocated by the function and needs to be freed by the application when finished with.Parameters: - con – a connection object
- to – the destination string
- from – the source string
- from_size – the length of the source string
Returns: the length of the ‘to’ string or -1 upon error due to empty parameters or overflow
-
void
drizzle_result_free
(drizzle_result_st *result)¶ Frees a result object
Parameters: - result – the result set to free
-
void
drizzle_result_free_all
(drizzle_st *con)¶ Frees all result objects for a given connection object
Parameters: - con – A connection object
-
drizzle_st*
drizzle_result_drizzle_con
(drizzle_result_st *result)¶ Gets the connection object from a given result object
Parameters: - result – A result object
Returns: The connection object associated to the result object
-
bool
drizzle_result_eof
(drizzle_result_st *result)¶ Tests to see if an EOF packet has been hit
Parameters: - result – A result object
Returns: true on EOF or false
-
const char*
drizzle_result_message
(drizzle_result_st *result)¶ Get error or information message from result set
Parameters: - result – A result object
Returns: The message to be returned
-
uint16_t
drizzle_result_error_code
(drizzle_result_st *result)¶ Gets the error code from a result set
Parameters: - result – A result object
Returns: The error code
-
const char*
drizzle_result_sqlstate
(drizzle_result_st *result)¶ Gets the SQL state from a result set
Parameters: - result – A result object
Returns: The SQL state string
-
uint16_t
drizzle_result_warning_count
(drizzle_result_st *result)¶ Gets the warning count from a result set
Parameters: - result – A result object
Retuns: The warning count
-
uint64_t
drizzle_result_insert_id
(drizzle_result_st *result)¶ Gets the insert ID for an auto_increment column in a result set
Note
With a MySQL server this returns the first ID with multiple inserts in a query.
Parameters: - result – A result object
Returns: The insert ID
-
uint64_t
drizzle_result_affected_rows
(drizzle_result_st *result)¶ Gets the affected row count from a result set
Parameters: - result – A result object
Returns: The affected row count
-
uint16_t
drizzle_result_column_count
(drizzle_result_st *result)¶ Gets the column count from a result set
Parameters: - result – A result object
Returns: The column count
-
uint64_t
drizzle_result_row_count
(drizzle_result_st *result)¶ Gets the row count from a result set buffered with
drizzle_result_buffer()
Parameters: - result – A result object
Returns: The row count
-
drizzle_result_st*
drizzle_result_read
(drizzle_st *con, drizzle_return_t *ret_ptr)¶ Reads the next result in a multi-result return
Parameters: - con – A connection object
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: The result struct for the new object
-
drizzle_return_t
drizzle_result_buffer
(drizzle_result_st *result)¶ Buffers a result set
Parameters: - result – A result object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
size_t
drizzle_result_row_size
(drizzle_result_st *result)¶ Get result row packet size in bytes.
Parameters: - result – Caller allocated structure.
Returns: size in bytes else 0
-
drizzle_result_st*
drizzle_column_drizzle_result
(drizzle_column_st *column)¶ Gets a result set for a given column object
Parameters: - column – A column object
Returns: A result object
-
const char*
drizzle_column_catalog
(drizzle_column_st *column)¶ Gets the catalog name for a given column
Parameters: - column – A column object
Returns: The catalog name
-
const char*
drizzle_column_db
(drizzle_column_st *column)¶ Gets the database name for a given column
Parameters: - column – A column object
Returns: The database name
-
const char*
drizzle_column_table
(drizzle_column_st *column)¶ Get the table name (or table alias) for a given column
Parameters: - column – A column object
Returns: The table name
-
const char*
drizzle_column_orig_table
(drizzle_column_st *column)¶ Gets the original table name (if an alias has been used) for a given column
Parameters: - column – A column object
Returns: The original table name
-
const char*
drizzle_column_name
(drizzle_column_st *column)¶ Gets the column name (or column alias) for a given column
Parameters: - column – A column object
Returns: The column name
-
const char*
drizzle_column_orig_name
(drizzle_column_st *column)¶ Gets the original column name (if an alias has been used) for a given column
Parameters: - column – A column object
Returns: The original column name
-
drizzle_charset_t
drizzle_column_charset
(drizzle_column_st *column)¶ Gets the character set ID for a given column
Parameters: - column – A column object
Returns: The character set ID
-
uint32_t
drizzle_column_size
(drizzle_column_st *column)¶ Gets the size of a given column
Parameters: - column – A column object
Returns: The column size
-
size_t
drizzle_column_max_size
(drizzle_column_st *column)¶ Gets the maximum size of a given column
Parameters: - column – A column object
Returns: The maximum size
-
drizzle_column_type_t
drizzle_column_type
(drizzle_column_st *column)¶ Gets the type of data for the column
Parameters: - column – A column object
Returns: The column type
-
const char *
drizzle_column_type_str
(drizzle_column_type_t type)¶ Get a column type as string
Parameters: - type – The table column type
Returns: The type of the column in human readable format
-
drizzle_column_flags_t
drizzle_column_flags
(drizzle_column_st *column)¶ Gets the flags for a given column
Parameters: - column – A column object
Returns: The column flags
-
uint8_t
drizzle_column_decimals
(drizzle_column_st *column)¶ Gets the number of decimal places for a given column
Parameters: - column – A column object
Returns: The number of decimal places
-
const unsigned char*
drizzle_column_default_value
(drizzle_column_st *column, size_t *size)¶ Gets the default value for a given column
Parameters: - column – A column object
Returns: A string containing the default value
-
drizzle_return_t
drizzle_column_skip
(drizzle_result_st *result)¶ Skips the next column in a result set when using
drizzle_column_read()
to get the column dataParameters: - result – A result object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_column_skip_all
(drizzle_result_st *result)¶ Skips all columns in a result set when using
drizzle_column_read()
to get the column dataParameters: - result – pointer to the structure to read from.
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
void
drizzle_column_free
(drizzle_column_st *column)¶ Frees a column when using
drizzle_column_read()
to get the column dataParameters: - column – The column to be freed
-
drizzle_column_st*
drizzle_column_read
(drizzle_result_st *result, drizzle_return_t *ret_ptr)¶ Reads a column from network buffer
Parameters: - result – A result object
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: A newly allocated column
-
drizzle_return_t
drizzle_column_buffer
(drizzle_result_st *result)¶ Buffers all the columns for a result set
Parameters: - result – A result object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_column_st*
drizzle_column_next
(drizzle_result_st *result)¶ Gets the next column in a buffered column result set
Parameters: - result – A result object
Returns: A column object
-
drizzle_column_st*
drizzle_column_prev
(drizzle_result_st *result)¶ Gets the previous column in a buffered column result set
Parameters: - result – A result object
Returns: A column object
-
void
drizzle_column_seek
(drizzle_result_st *result, uint16_t column)¶ Seeks to a given column in a buffered column result set
Parameters: - result – A result object
- column – The column number
-
drizzle_column_st*
drizzle_column_index
(drizzle_result_st *result, uint16_t column)¶ Gets a given column in a column buffered result set
Parameters: - result – A result object
- column – The column number
Returns: A column object
-
uint16_t
drizzle_column_current
(drizzle_result_st *result)¶ Gets the column number in a buffered or unbuffered column result set
Parameters: - result – A result object:
Returns: The column number
-
uint64_t
drizzle_row_read
(drizzle_result_st *result, drizzle_return_t *ret_ptr)¶ Reads the next row header and returns the row number for unbuffered row reads. Use
drizzle_field_read()
ordrizzle_field_buffer()
to get the field data after this call.Parameters: - result – A result object
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: The row number
-
drizzle_row_t
drizzle_row_buffer
(drizzle_result_st *result, drizzle_return_t *ret_ptr)¶ Read and buffer one entire row, must be freed with c:func:drizzle_row_free
Parameters: - result – A result object
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: The newly allocated row buffer
-
void
drizzle_row_free
(drizzle_result_st *result, drizzle_row_t row)¶ Free a buffered row read
Parameters: - result – A result object
- row – The row data to be freed
-
size_t*
drizzle_row_field_sizes
(drizzle_result_st *result)¶ Gets an array of the field sizes for buffered rows
Parameters: - result – A result object
Returns: An array of row sizes
-
drizzle_row_t
drizzle_row_next
(drizzle_result_st *result)¶ Gets the next row in a buffered result set
Parameters: - result – A result object
Returns: The row data
-
drizzle_row_t
drizzle_row_prev
(drizzle_result_st *result)¶ Gets the previous row in a buffered result set
Parameters: - result – A result object
Returns: The row data
-
void
drizzle_row_seek
(drizzle_result_st *result, uint64_t row)¶ Seeks to a given row in a buffered result set
Parameters: - result – A result object
- row – The row number to seek to
-
drizzle_row_t
drizzle_row_index
(drizzle_result_st *result, uint64_t row)¶ Gets a row at the given index in a buffered result set
Parameters: - result – A result object
- row – The row number to get
Returns: The row data
-
uint64_t
drizzle_row_current
(drizzle_result_st *result)¶ Gets the current row number
Parameters: - result – A result object
Returns: The row number
-
drizzle_field_t
drizzle_field_read
(drizzle_result_st *result, size_t *offset, size_t *size, size_t *total, drizzle_return_t *ret_ptr)¶ Reads the next field from the network buffer. Useful for large blobs without buffering the entire blob.
Parameters: - result – A result object
- offset – The offset position of the blob for this read, to be written to by the function
- size – The size of the read, to be written to by the function
- total – The total size of the field, to be written to by the function
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: The field data
-
drizzle_field_t
drizzle_field_buffer
(drizzle_result_st *result, size_t *total, drizzle_return_t *ret_ptr)¶ Read and buffer the entire field for an unbuffered row read.
Parameters: - result – A result object
- total – The total size of the field, to be written to by the function
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: The field data
-
void
drizzle_field_free
(drizzle_field_t field)¶ Frees field data for unbuffered row reads
Parameters: - field – The field data to free