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 data

Parameters:
  • 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 data

Parameters:
  • 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 data

Parameters:
  • 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() or drizzle_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