Package mysql :: Package stmt :: Module stmt :: Class Statement
[hide private]
[frames] | no frames]

Class Statement



object --+
         |
        Statement

Parsed SQL statement object.

This object represents a parsed statement on the server-side. It provides the ability to efficiently re-execute the same SQL statement.

Statement objects should only be created by the mysql.connection.Connection.new_statement method.

Note Creating a new Statement object will close any live unbuffered result objects and reset any live statement objects.

Note that when deleting a Statement object the system may delay deleting the actual structure stored on the server-side if you have not explicitly called close. This is because the close method requires communicating with the server, and if you are in the middle of an unbuffered fetch, it would reset the state of the connection. The Statement object may be involved in a reference cycle, and thus would only get removed by the garbage collector which can fire at unexpected times. It accomplishes this by putting the MySQL data structure into a special holding area in the Connection object, which is checked periodically at safe opportunities.



Instance Methods [hide private]
  __init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  __new__(T, S, ...)
Returns a new object with type S, a subtype of T...
  _raise_error(...)
Raise a statement-API error.
  affected_rows(...)
Return the number of rows affected.
  bind_input(...)
Bind input variables.
  bind_output(...)
Bind output variables.
  close(...)
Close the statement object, releasing any internally held memory.
  closed(...)
Check if the statement is closed.
  execute(...)
Execute the SQL statement.
  fetch(...)
Fetch one row of data.
  field_count(...)
Return the number of output fields.
  fields(...)
Get information about the fields in the result.
  free_result(...)
Release memory used by internal result buffers.
  get_param_count(...)
Return the number of parameter markers in the query.
  get_prefetch_rows(...)
Get the number of rows that will be prefetched when using a cursor.
  get_update_max_length(...)
Determine if MySQL is currently set to compute the max_length attribute in the field objects.
  get_use_cursor(...)
Determine whether or not a server-side cursor will be used for fetching results.
  insert_id(...)
Get the ID generated for an AUTO_INCREMENT column.
  num_rows(...)
Return the number of rows in the result set.
  reset(...)
Clear all state.
  row_seek(...)
Set the current row position.
  row_tell(...)
Indicate the current row position.
  set_prefetch_rows(...)
Set the number of rows to prefetch when using a cursor.
  set_update_max_length(...)
Tell MySQL to compute the max_length attribute in the field objects.
  set_use_cursor(...)
When fetching results, use a cursor.
  sqlstate(...)
Return the current SQL state.

Inherited from object: __delattr__, __getattribute__, __hash__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__


Class Variables [hide private]
  __pyx_vtable__ = <PyCObject object at 0x852eb60>

Instance Variables [hide private]
  _connection = <member '_connection' of 'mysql.stmt.stmt.Statement'...
Reference to the connection that created this statement.
  _input_binds
List or tuple of mysql.stmt.bind_in.Input_Bind instances.
  _old_statements
The mysql.connection._Statement_Cleaner instance from the connection object.
  _output_binds
List or tuple of mysql.stmt.bind_out.Output_Bind instances.
  _stmt
MYSQL_STMT structure.
  _stored
Whether or not the result was stored in the execute method.

Properties [hide private]

Inherited from object: __class__


Method Details [hide private]

__init__(...)
(Constructor)

 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature
Overrides: object.__init__

__new__(T, S, ...)

 
Returns:
a new object with type S, a subtype of T

Overrides: object.__new__

_raise_error(...)

 

Raise a statement-API error.

affected_rows(...)

 

Return the number of rows affected.

Note For SELECT queries, this is only available if the result was stored by passing True to the store_result parameter in the execute call.

Rows "affected" is defined as rows that were actually modified by an UPDATE, INSERT, or DELETE statement. All other statements return zero.

Returns:
Returns the number of rows affected.
Raises:

bind_input(...)

 

Bind input variables.

This binds the objects that will be inspected for input variables. You should pass in the appropriate mysql.stmt.bind_in.Input_Bind instances as arguments in the appropriate order. See the mysql.stmt.bind_in docs for more detail.

If you call this again, it will reset the bindings.

Raises:

bind_output(...)

 

Bind output variables.

This binds where the output for each fetch will go. You should pass in the appropriate mysql.stmt.bind_out.Output_Bind instances as arguments in the appropriate order. See the mysql.stmt.bind_out docs for more detail.

If you call this again, it will reset the bindings.

Raises:

close(...)

 

Close the statement object, releasing any internally held memory.

This will render this Statement object useless.

This is automatically called when the object is deleted.

If the result is already closed, this does nothing.

Further attempts to use the result object will raise mysql.exceptions.Statement_Closed_Error.

Note This will close any live unbuffered result objects and reset any live statement objects.

Raises:

closed(...)

 

Check if the statement is closed.

This can be used to check if the statement has been closed with the close method. This is the only method you may call (besides close) on a closed Statement object.

Returns:
Returns True if this Statement object is closed, False if it is still live.

execute(...)

 

Execute the SQL statement.

Note This will close any live unbuffered result objects and reset any live statement objects.

Parameters:
  • store_result - Whether or not to fetch the entire result from the server immediately for SELECT-like queries. If False, results will be fetched from the server on an as-needed basis. Defaults to False. Note that some methods in the Statement object are not available if this is False.

    Beware that setting this to True may use a lot of memory.

    However, setting this to False will tie up server resources, thus you shouldn't do that if you may be taking a long time to fetch the results.

    By default, fetching data with a Statement object fetches one row of data from the server at a time. You may enable partial buffering by creating a server-side cursor by calling set_use_cursor. In this case you can control how many results are buffered on the client side with the set_prefetch_rows method. Generally the Statement object will behave the same as-if store_result is False when using a cursor.

    On MySQL version 5.0.18 and earlier, setting store_result to True when you have enabled server-side cursors will result in a mysql.exceptions.Commands_Out_Of_Sync. Later versions will fetch all rows.

    Note You can only have 1 live "unbuffered" (False) result set at once. You must fetch all rows (until mysql.exceptions.No_More_Rows is raised) or call close on the result before executing another statement. If you do not do that, then this method will automatically call close on your old result object for you! Several other methods in the Connection and Statement objects will also force a close. This is indicated in those method's docstrings.

Raises:

fetch(...)

 

Fetch one row of data.

Note This will close any live unbuffered result objects and reset any live statement objects.

Raises:

field_count(...)

 

Return the number of output fields.
Returns:
Returns the number of output fields. This is zero for statements like INSERT or DELETE that do not produce output.
Raises:

fields(...)

 

Get information about the fields in the result.

This returns a list of mysql.result.Field objects which you can use to inspect the types of fields in the result.

Note that the max_length member of the Field object is only computed if you have called set_update_max_length.

Returns:
Returns a list of mysql.result.Field instances that describe the columns in a query.
Raises:

free_result(...)

 

Release memory used by internal result buffers.

This process is normally taken care of when the Statement object is deleted, but you can call this to proactively free some memory.

Raises:

get_param_count(...)

 

Return the number of parameter markers in the query.
Returns:
Returns an integer of the number of markers in the query.
Raises:

get_prefetch_rows(...)

 

Get the number of rows that will be prefetched when using a cursor.
Raises:

get_update_max_length(...)

 

Determine if MySQL is currently set to compute the max_length attribute in the field objects.
Returns:
Returns True if the max_length parameter will be set, False otherwise.
Raises:

get_use_cursor(...)

 

Determine whether or not a server-side cursor will be used for fetching results.
Raises:

insert_id(...)

 

Get the ID generated for an AUTO_INCREMENT column.

The result is undefined for statements that do not update an AUTO_INCREMENT column.

Returns:
Returns the ID generated by an INSERT or UPDATE statement.
Raises:

num_rows(...)

 

Return the number of rows in the result set.

Note For SELECT queries, this is only available if the result was stored by passing True to the store_result parameter in the execute call.

The result is undefined for non-SELECT statements.

Returns:
Returns the number of rows returned from the query.
Raises:

reset(...)

 

Clear all state.

This will clear internal buffers and state on the client and the server. This releases the connection after doing a SELECT-like query, allowing you to perform other tasks.

Parameters:
  • reset_binds - If True, will remove all input and output binds (resetting the state as-if you recreate the Statement object from scratch). This defaults to False.
Raises:

row_seek(...)

 

Set the current row position.

Note For SELECT queries, this is only available if the result was stored by passing True to the store_result parameter in the execute call.

Parameters:
  • offset - An offset object returned from row_tell or an integer of an explicit row number (starting at zero). If it is a number, it must be a number from 0 to num_rows()-1.
Returns:
Returns the previous row offset as a mysql.result.Row_Offset instance.
Raises:

row_tell(...)

 

Indicate the current row position.

Note For SELECT queries, this is only available if the result was stored by passing True to the store_result parameter in the execute call.

It returns an opaque object to be used with row_seek.

Returns:
Returns a mysql.result.Row_Offset instance.
Raises:

set_prefetch_rows(...)

 

Set the number of rows to prefetch when using a cursor.

The default is 1.

Parameters:
  • num - The number of rows to prefetch when using a cursor.
Raises:

set_update_max_length(...)

 

Tell MySQL to compute the max_length attribute in the field objects.

Note that this will slow down execution of queries.

This must be called before the data is fetched.

Raises:

set_use_cursor(...)

 

When fetching results, use a cursor.

When the store_result attribute is set to False (the default) in the execute method, results are normally fetched one row at a time. Before executing the query, you can call this method to tell MySQL to fetch a few rows at a time. Use the set_prefetch_rows method to control the number of rows buffered at one time.

Raises:

sqlstate(...)

 

Return the current SQL state.
Returns:
Returns a 5-character string. A value of '00000' means "no error". A value of 'HY000' is for a MySQL state that is not yet mapped to a standard state.
Raises:

Class Variable Details [hide private]

__pyx_vtable__

Value:
<PyCObject object at 0x852eb60>                                        
      

Instance Variable Details [hide private]

_connection


Reference to the connection that created this statement. (Read only.)
Value:
<member '_connection' of 'mysql.stmt.stmt.Statement' objects>          
      

_input_binds


List or tuple of mysql.stmt.bind_in.Input_Bind instances. (C only.)

_old_statements


The mysql.connection._Statement_Cleaner instance from the connection object. We hold a local refernce to this object because the connection and statement objects are involved in a cycle, and thus we can't rely on the _connection object existing during dealloc.

_output_binds


List or tuple of mysql.stmt.bind_out.Output_Bind instances. (C only.)

_stmt


MYSQL_STMT structure. May be NULL. (C only.)

_stored


Whether or not the result was stored in the execute method. (C only.)