Represents a connection to the MySQL server. All parameters which are not provided will use MySQL’s defaults. For the exact semantics, see the documentation for the :mysqlfunc:`mysql_real_connect` and :mysqlfunc:`mysql_options` functions.
Parameters: |
|
---|
Calls the :mysqlfunc:`mysql_ping` function. If autoconnection is enabled, this will transparently reestablish the connection. The exact semantics of what happens when a reconnection happens are more thoroughly documented in MySQL’s developer reference manual.
Commits the current active transaction on the connection.
Rolls back the current active transaction on the connection.
Completely closes the connection. None of the methods and most of the attributes on the connection will no longer be usable. This will also rollback any active transaction on the connection.
Create a cursor associated with this connection.
Parameters: | cursor_class – Specify the class of the cursor returned. If nothing is passed, use the default_cursor attribute. |
---|
Extra options can be passed to the cursor by keyword:
Parameters: |
|
---|
connect() is simply an alias to the Connection class.
Connections can also be used as context managers:
with some_connection as cursor:
do_something_with(cursor)
This behaves the same way as using a cursor as a context manager.
Cursors of any sort should never be instantiated directly. Currently, the only real difference between cursor classes is how they return fetched rows. Iterating over a cursor is the same as repeatedly calling fetchone():
curs.execute('SELECT a, b FROM `some_table`')
curs.execute('SELECT c, d FROM `some_other_table`')
# result set one:
for a, b in curs:
do_whatever_with(a, b)
# result set two:
for c, d in curs:
do_whatever_with(a, b)
Cursors can also be used as context managers:
with some_connection.cursor() as cursor:
do_something_with(cursor)
Is equivalent to:
cursor = some_connection.cursor()
try:
do_something_with(cursor)
except:
some_connection.rollback()
raise
else:
some_connection.commit()
finally:
cursor.close()
Cursor instances represent rows as tuples.
Close the cursor and discard the rest of the results. The cursor will immediately become unusable.
Supposedly, run a stored procedure. MySQL’s C API has no direct call for this; you need to execute stored procedures with the CALL statement instead. Calling this method always raises a NotSupportedError.
Execute a query. If plain_query is true, run a plain, unparameterized query. MySQL cannot parameterize all kinds of statements, which makes it sometimes necessary to execute a plain query. If plain_query is true and params is true, an exception will be raised as plain queries cannot be parameterized.
Plain queries also have some associated caveats:
Execute the same query with different sets of parameters. This is more efficient than calling execute many times with the same query.
Move to the next result set. If there are any result sets left, this returns True. Otherwise, None.
Fetch one row from the current result set. If the result set was previously exhausted, this returns None and moves to the next result set. If there were no result sets, a ProgrammingError is raised.
Fetch up to size rows. If there aren’t that many rows available in the result set, this returns as many as were available. If the result set was previously exhausted, this returns an empty list and moves to the next result set. If there were no result sets, a ProgrammingError is raised.
Fetch all available rows from every result set. This will immediately buffer all the results client-side. For large result sets, it can be more performant to iterate over the cursor or use fetchmany(). If there were no result sets, a ProgrammingError is raised.
A nonzero positive integer which controls the default number of rows returned when calling fetchmany() with no arguments. The default value is 1.
As documented in PEP 249: a seven-tuple of (name, type_code, display_size, internal_size, precision, scale, null_ok).
The rowid of the last inserted or updated row. For a full discussion of the semantics, see the documentation for the :mysqlfunc:`mysql_insert_id` function.
If executemany() was called, lastrowid will reflect the rowid for the last set of parameters that were passed.
The number of rows affected by the last query. For a full discussion of the semantics, see the documentation for the :mysqlfunc:`mysql_affected_rows` function. Also note that the found_rows parameter to Connection, which controls the CLIENT_FOUND_ROWS flag, defaults to True.
DictCursor instances represent rows as dicts mapping column names or aliases to values. These key names are taken from the description attribute of the cursor, and are therefore affected by the show_table cursor option. A ProgrammingError is raised when fetching a row if there were duplicate keys with inequal values.
IterWrapper is a wrapper class for arbitrary string-yielding iterable objects so that their contents can be streamed over the wire as a bound parameter for a query. The strings are assumed to be text and not arbitrary bytes.
BinaryIterWrapper behaves like IterWrapper, except the strings yielded from the iterable are treated as bytes instead of text strings.
FileWrapper is a wrapper class for file-like objects so that their contents can be streamed over the wire as a bound parameter for a query. Strings read from the wrapped file are assumed to be text and not arbitrary bytes.
Strings will be read by calling the read() method on the file object with chunksize as the only parameter parameter until it returns the empty string. If doclose is true, the file will have its close() method called once it has been exhausted.
BinaryFileWrapper behaves exactly like FileWrapper, except the strings yielded from the file object are treated as bytes instead of text strings.
A dict mapping MySQL error names to errnos, e.g. oursql.errnos['ER_ACCESS_DENIED_ERROR'] == 1045.
Some exception descriptions are lovingly stolen from PEP 249.
This is the base class for all the oursql-defined error exceptions.
For errors originating from MySQL, this will be set to an integer representing the exact MySQL errno. Errors originating from oursql will have an errno of None. See also the errnos dict.
Contains extra information about the error. This is currently only used by the CollatedWarningsError exception.
This exception represents errors that are related to the interface to the database instead of the database itself.
This exception represents errors that are related to the database.
This exception represents errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.
This exception represents errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.
This exception represents errors that are related to when the relational integrity of the database is affected, e.g. a foreign key check fails.
This exception represents errors that are related to when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.
This exception represents programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc.
This exception represents that the requested action is not supported by either MySQL or oursql.
This exception represents that the current user did not have sufficient permissions to perform the requested action.