MySQL  8.0.17
Source Code Documentation
Prepared_statement Class Referencefinal

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_CSTRINGname () 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_stmtget_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
 
THDthd
 
Item_param ** param_array
 
Server_side_cursorcursor
 
uint param_count
 
uint last_errno
 
char last_error [MYSQL_ERRMSG_SIZE]
 
const ulong id
 
LEXlex
 
LEX_CSTRING m_query_string
 The query associated with this statement. More...
 
PSI_prepared_stmtm_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_sendresult
 
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

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_queryA query for binlogging which has all parameter markers ('?') replaced with their actual values.
open_cursorTrue 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
falseok
trueError

◆ 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_queryQuery string.
open_cursorFlag to specift if a cursor should be used.
Returns
a bool value representing the function execution status.
Return values
trueerror: either MAX_REPREPARE_ATTEMPTS has been reached, or some general error
falsesuccessfully 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
0if success
1otherwise

◆ 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
varnamesList of variables. Caller must ensure that number of variables in the list is equal to number of statement parameters
queryThe 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_strstatement text
query_lengththe 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
truean error occurred. Possible errors include incompatibility of new and old result set metadata
falsesuccess, 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,
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_querya 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_typesflag used to signal that new types are provided.
parametersprepared statement's parsed parameters.
Returns
bool representing the function execution status.
Return values
truean error occurred when assigning a parameter (likely a conversion error or out of memory, or malformed packet)
falsesuccess

◆ set_parameters() [2/2]

bool Prepared_statement::set_parameters ( String expanded_query)

◆ 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]copythe re-prepared prepared statement to verify the metadata of
Return values
trueerror, ER_PS_REBIND is reported
falsestatement 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: