Prepared_statement Class Reference

Prepared_statement: a statement that can contain placeholders. More...

#include <sql_prepare.h>

Public Member Functions
	Prepared_statement (THD *thd_arg)
virtual	~Prepared_statement ()
	Destroy this prepared statement, cleaning up all used memory and resources. More...
bool	set_name (const LEX_CSTRING &name)
const LEX_CSTRING &	name () const
void	close_cursor ()
bool	is_in_use () const
bool	is_sql_prepare () const
void	set_sql_prepare ()
bool	prepare (const char *packet, size_t packet_length)
	Parse statement text, validate the statement, and prepare it for execution. More...
bool	execute_loop (String *expanded_query, bool open_cursor)
	Execute a prepared statement. More...
bool	execute_server_runnable (Server_runnable *server_runnable)
PSI_prepared_stmt *	get_PS_prepared_stmt ()
void	deallocate ()
	Common part of DEALLOCATE PREPARE and mysqld_stmt_close. More...
bool	set_parameters (String *expanded_query, bool has_new_types, PS_PARAM *parameters)
	Assign parameter values either from variables, in case of SQL PS or from the execute packet. More...
bool	set_parameters (String *expanded_query)

Public Attributes
Query_arena	m_arena
THD *	thd
Item_param **	param_array
Server_side_cursor *	cursor
uint	param_count
uint	last_errno
char	last_error [MYSQL_ERRMSG_SIZE]
const ulong	id
LEX *	lex
LEX_CSTRING	m_query_string
	The query associated with this statement. More...
PSI_prepared_stmt *	m_prepared_stmt

Private Types
enum	flag_values { IS_IN_USE = 1, IS_SQL_PREPARE = 2 }

Private Member Functions
void	cleanup_stmt ()
void	setup_set_params ()
bool	set_db (const LEX_CSTRING &db_length)
	Remember the current database. More...
bool	execute (String *expanded_query, bool open_cursor)
	Execute a prepared statement. More...
bool	reprepare ()
	Reprepare this prepared statement. More...
bool	validate_metadata (Prepared_statement *copy)
	Validate statement result set metadata (if the statement returns a result set). More...
void	swap_prepared_statement (Prepared_statement *copy)
	Replace the original prepared statement with a prepared copy. More...
bool	insert_params_from_vars (List< LEX_STRING > &varnames, String *query)
	Assign prepared statement parameters from user variables. More...
bool	insert_params (String *query, PS_PARAM *parameters)
	Routines to assign parameters from data supplied by the client. More...

Private Attributes
Query_result_send *	result
uint	flags
bool	with_log
LEX_CSTRING	m_name
LEX_CSTRING	m_db
	Name of the current (default) database. More...
MEM_ROOT	main_mem_root
	The memory root to allocate parsed tree elements (instances of Item, SELECT_LEX and other classes). More...

Detailed Description

Prepared_statement: a statement that can contain placeholders.

Member Enumeration Documentation

flag_values

enum Prepared_statement::flag_values

private

Enumerator
IS_IN_USE
IS_SQL_PREPARE

Constructor & Destructor Documentation

Prepared_statement()

Prepared_statement::Prepared_statement

(

THD *

thd_arg

)

~Prepared_statement()

Prepared_statement::~Prepared_statement ( )

virtual

Destroy this prepared statement, cleaning up all used memory and resources.

This is called from deallocate() to handle COM_STMT_CLOSE and DEALLOCATE PREPARE or when THD ends and all prepared statements are freed.

Member Function Documentation

cleanup_stmt()

void Prepared_statement::cleanup_stmt ( )

private

close_cursor()

void Prepared_statement::close_cursor

(

)

deallocate()

void Prepared_statement::deallocate

(

)

Common part of DEALLOCATE PREPARE and mysqld_stmt_close.

execute()

bool Prepared_statement::execute ( String *  expanded_query, bool  open_cursor  )

private

Execute a prepared statement.

You should not change global THD state in this function, if at all possible: it may be called from any context, e.g. when executing a COM_* command, and SQLCOM_* command, or a stored procedure.

Parameters

expanded_query	A query for binlogging which has all parameter markers ('?') replaced with their actual values.
open_cursor	True if an attempt to open a cursor should be made. Currenlty used only in the binary protocol.

Note

Preconditions, postconditions.

• See the comment for Prepared_statement::prepare().

Return values

false	ok
true	Error

execute_loop()

bool Prepared_statement::execute_loop	(	String *	expanded_query,
		bool	open_cursor
	)

Execute a prepared statement.

Re-prepare it a limited number of times if necessary.

Try to execute a prepared statement. If there is a metadata validation error, prepare a new copy of the prepared statement, swap the old and the new statements, and try again. If there is a validation error again, repeat the above, but perform no more than MAX_REPREPARE_ATTEMPTS.

Note

We have to try several times in a loop since we release metadata locks on tables after prepared statement prepare. Therefore, a DDL statement may sneak in between prepare and execute of a new statement. If this happens repeatedly more than MAX_REPREPARE_ATTEMPTS times, we give up.

Parameters

expanded_query	Query string.
open_cursor	Flag to specift if a cursor should be used.

Returns

a bool value representing the function execution status.

Return values

true	error: either MAX_REPREPARE_ATTEMPTS has been reached, or some general error
false	successfully executed the statement, perhaps after having reprepared it a few times.

execute_server_runnable()

bool Prepared_statement::execute_server_runnable

(

Server_runnable *

server_runnable

)

get_PS_prepared_stmt()

PSI_prepared_stmt* Prepared_statement::get_PS_prepared_stmt ( )

inline

insert_params()

bool Prepared_statement::insert_params ( String *  query, PS_PARAM *  parameters  )

private

Routines to assign parameters from data supplied by the client.

Update the parameter markers by reading data from the packet and and generate a valid query for logging.

Note

with_log is set when one of slow or general logs are open. Logging of prepared statements in all cases is performed by means of regular queries: if parameter data was supplied from C API, each placeholder in the query is replaced with its actual value; if we're logging a [Dynamic] SQL prepared statement, parameter markers are replaced with variable names. Example:

   mysqld_stmt_prepare("UPDATE t1 SET a=a*1.25 WHERE a=?")
     --> general logs gets [Prepare] UPDATE t1 SET a*1.25 WHERE a=?"
   mysqld_stmt_execute(stmt);
     --> general and binary logs get
                           [Execute] UPDATE t1 SET a*1.25 WHERE a=1"

If a statement has been prepared using SQL syntax:

   PREPARE stmt FROM "UPDATE t1 SET a=a*1.25 WHERE a=?"
     --> general log gets
                               [Query]   PREPARE stmt FROM "UPDATE ..."
   EXECUTE stmt USING @a
     --> general log gets
                           [Query]   EXECUTE stmt USING @a;

Return values

0	if success
1	otherwise

insert_params_from_vars()

bool Prepared_statement::insert_params_from_vars ( List< LEX_STRING > &  varnames, String *  query  )

private

Assign prepared statement parameters from user variables.

If with_log is set, also construct query test for binary log.

Parameters

varnames	List of variables. Caller must ensure that number of variables in the list is equal to number of statement parameters
query	The query with parameter markers replaced with corresponding user variables that were used to execute the query.

is_in_use()

bool Prepared_statement::is_in_use ( ) const

inline

is_sql_prepare()

bool Prepared_statement::is_sql_prepare ( ) const

inline

name()

const LEX_CSTRING& Prepared_statement::name ( ) const

inline

prepare()

bool Prepared_statement::prepare	(	const char *	query_str,
		size_t	query_length
	)

Parse statement text, validate the statement, and prepare it for execution.

You should not change global THD state in this function, if at all possible: it may be called from any context, e.g. when executing a COM_* command, and SQLCOM_* command, or a stored procedure.

Parameters

query_str	statement text
query_length	the length of the statement text

Note

Precondition: The caller must ensure that thd->change_list and thd->item_list is empty: this function will not back them up but will free in the end of its execution.

Postcondition: thd->mem_root contains unused memory allocated during validation.

reprepare()

bool Prepared_statement::reprepare ( )

private

Reprepare this prepared statement.

Currently this is implemented by creating a new prepared statement, preparing it with the original query and then swapping the new statement and the original one.

Return values

true	an error occurred. Possible errors include incompatibility of new and old result set metadata
false	success, the statement has been reprepared

set_db()

bool Prepared_statement::set_db ( const LEX_CSTRING &  db_arg )

private

Remember the current database.

We must reset/restore the current database during execution of a prepared statement since it affects execution environment: privileges, @character_set_database, and other.

Returns

Returns an error if out of memory.

set_name()

bool Prepared_statement::set_name

(

const LEX_CSTRING &

name

)

set_parameters() [1/2]

bool Prepared_statement::set_parameters

(

String *

expanded_query

)

set_parameters() [2/2]

bool Prepared_statement::set_parameters	(	String *	expanded_query,
		bool	has_new_types,
		PS_PARAM *	parameters
	)

Assign parameter values either from variables, in case of SQL PS or from the execute packet.

Parameters

expanded_query	a container with the original SQL statement. '?' placeholders will be replaced with their values in case of success. The result is used for logging and replication
has_new_types	flag used to signal that new types are provided.
parameters	prepared statement's parsed parameters.

Returns

bool representing the function execution status.

Return values

true	an error occurred when assigning a parameter (likely a conversion error or out of memory, or malformed packet)
false	success

set_sql_prepare()

void Prepared_statement::set_sql_prepare ( )

inline

setup_set_params()

void Prepared_statement::setup_set_params ( )

private

swap_prepared_statement()

void Prepared_statement::swap_prepared_statement ( Prepared_statement *  copy )

private

Replace the original prepared statement with a prepared copy.

This is a private helper that is used as part of statement reprepare.

validate_metadata()

bool Prepared_statement::validate_metadata ( Prepared_statement *  copy )

private

Validate statement result set metadata (if the statement returns a result set).

Currently we only check that the number of columns of the result set did not change. This is a helper method used during re-prepare.

Parameters

[in]

copy

the re-prepared prepared statement to verify the metadata of

Return values

true	error, ER_PS_REBIND is reported
false	statement return no or compatible metadata

If this is an SQL prepared statement or EXPLAIN, return false – the metadata of the original SELECT, if any, has not been sent to the client.

Column counts mismatch, update the client

Member Data Documentation

cursor

Server_side_cursor* Prepared_statement::cursor

flags

uint Prepared_statement::flags

private

id

const ulong Prepared_statement::id

last_errno

uint Prepared_statement::last_errno

last_error

char Prepared_statement::last_error[MYSQL_ERRMSG_SIZE]

lex

LEX* Prepared_statement::lex

m_arena

Query_arena Prepared_statement::m_arena

m_db

LEX_CSTRING Prepared_statement::m_db

private

Name of the current (default) database.

If there is the current (default) database, "db" contains its name. If there is no current (default) database, "db" is NULL and "db_length" is 0. In other words, "db", "db_length" must either be NULL, or contain a valid database name.

Note

this attribute is set and alloced by the slave SQL thread (for the THD of that thread); that thread is (and must remain, for now) the only responsible for freeing this member.

m_name

LEX_CSTRING Prepared_statement::m_name

private

m_prepared_stmt

PSI_prepared_stmt* Prepared_statement::m_prepared_stmt

m_query_string

LEX_CSTRING Prepared_statement::m_query_string

The query associated with this statement.

main_mem_root

MEM_ROOT Prepared_statement::main_mem_root

private

The memory root to allocate parsed tree elements (instances of Item, SELECT_LEX and other classes).

param_array

Item_param** Prepared_statement::param_array

param_count

uint Prepared_statement::param_count

result

Query_result_send* Prepared_statement::result

private

thd

THD* Prepared_statement::thd

with_log

bool Prepared_statement::with_log

private

---

The documentation for this class was generated from the following files:

• sql/sql_prepare.h
• sql/sql_prepare.cc