mysql.stmt.stmt.Statement

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: `mysql.exceptions.Affected_Rows_Unavailable` - The query was not successful, or for SELECT queries, `store_result` was not set. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed. `OverflowError` - One of the input values did not fit into buffer type of the input binding. `TypeError` - One of the input values did not match the type of the input binding.

### fetch(...) |
Fetch one row of data. Note This will close any live unbuffered result objects and reset any live statement objects. Raises: `mysql.exceptions.No_More_Rows` - There is no more data. `mysql.exceptions.Data_Truncated` - The data was truncated. You can inspect the "error" field of the mysql.stmt.bind_out.Output_Bind objects to figure out which field was truncated. `mysql.exceptions.Unsupported_Param_Type` - date, time, datetime, or timestamp parameter type did not match the column type. `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### get_prefetch_rows(...) |
Get the number of rows that will be prefetched when using a cursor. Raises: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### get_use_cursor(...) |
Determine whether or not a server-side cursor will be used for fetching results. Raises: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.MySQL_Error` - Generic MySQL error. `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed. `mysql.exceptions.Result_Unbuffered_Error` - The result is in unbuffered mode (`store_result` was set to False).

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed. `mysql.exceptions.Result_Unbuffered_Error` - The result is in unbuffered mode (`store_result` was set to False).

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

### 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: `mysql.exceptions.Statement_Closed_Error` - close has been called on this object. `mysql.exceptions.Not_Connected_Error` - The connection has been closed.

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.)