_mysql Module

an adaptation of the MySQL C API (mostly)

You probably are better off using MySQLdb instead of using this module directly.

In general, renaming goes from mysql_* to _mysql.*. _mysql.connect() returns a connection object (MYSQL). Functions which expect MYSQL * as an argument are now methods of the connection object. A number of things return result objects (MYSQL_RES). Functions which expect MYSQL_RES * as an argument are now methods of the result object. Deprecated functions (as of 3.23) are NOT implemented.

_mysql.connect()

Returns a MYSQL connection object. Exclusive use of keyword parameters strongly recommended. Consult the MySQL C API documentation for more details.

host
string, host to connect
user
string, user to connect as
passwd
string, password to use
db
string, database to use
port
integer, TCP/IP port to connect to
unix_socket
string, location of unix_socket (UNIX-ish only)
conv
mapping, maps MySQL FIELD_TYPE.* to Python functions which convert a string to the appropriate Python type
connect_timeout
number of seconds to wait before the connection attempt fails.
compress
if set, gzip compression is enabled
named_pipe
if set, connect to server via named pipe (Windows only)
init_command
command which is run once the connection is created
read_default_file
see the MySQL documentation for mysql_options()
read_default_group
see the MySQL documentation for mysql_options()
client_flag
client flags from MySQLdb.constants.CLIENT
load_infile
int, non-zero enables LOAD LOCAL INFILE, zero disables
class _mysql.connection

Bases: object

Returns a MYSQL connection object. Exclusive use of keyword parameters strongly recommended. Consult the MySQL C API documentation for more details.

host
string, host to connect
user
string, user to connect as
passwd
string, password to use
db
string, database to use
port
integer, TCP/IP port to connect to
unix_socket
string, location of unix_socket (UNIX-ish only)
conv
mapping, maps MySQL FIELD_TYPE.* to Python functions which convert a string to the appropriate Python type
connect_timeout
number of seconds to wait before the connection attempt fails.
compress
if set, gzip compression is enabled
named_pipe
if set, connect to server via named pipe (Windows only)
init_command
command which is run once the connection is created
read_default_file
see the MySQL documentation for mysql_options()
read_default_group
see the MySQL documentation for mysql_options()
client_flag
client flags from MySQLdb.constants.CLIENT
load_infile
int, non-zero enables LOAD LOCAL INFILE, zero disables
affected_rows()

Return number of rows affected by the last query. Non-standard. Use Cursor.rowcount.

autocommit()

Set the autocommit mode. True values enable; False value disable.

change_user()

Changes the user and causes the database specified by db to become the default (current) database on the connection specified by mysql. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.

This function was introduced in MySQL Version 3.23.3.

Fails unless the connected user can be authenticated or if he doesn’t have permission to use the database. In this case the user and database are not changed.

The db parameter may be set to None if you don’t want to have a default database.

character_set_name()

Returns the default character set for the current connection. Non-standard.

client_flag

Client flags; refer to MySQLdb.constants.CLIENT

close()

Close the connection. No further activity possible.

commit()

Commits the current transaction

converter

Type conversion mapping

dump_debug_info()

Instructs the server to write some debug information to the log. The connected user must have the process privilege for this to work. Non-standard.

errno()

Returns the error code for the most recently invoked API function that can succeed or fail. A return value of zero means that no error occurred.

error()

Returns the error message for the most recently invoked API function that can succeed or fail. An empty string () is returned if no error occurred.

escape()

escape(obj, dict) – escape any special characters in object obj using mapping dict to provide quoting functions for each type. Returns a SQL literal string.

escape_string()

escape_string(s) – quote any SQL-interpreted characters in string s.

Use connection.escape_string(s), if you use it at all. _mysql.escape_string(s) cannot handle character sets. You are probably better off using connection.escape(o) instead, since it will escape entire sequences as well as strings.

field_count()

Returns the number of columns for the most recent query on the connection. Non-standard. Will probably give you bogus results on most cursor classes. Use Cursor.rowcount.

fileno()

Return underlaying fd for connection

get_autocommit()

Get the autocommit mode. True when enable; False when disable.

get_character_set_info()

Returns a dict with information about the current character set:

collation
collation name
name
character set name
comment
comment or descriptive name
dir
character set directory
mbminlen
min. length for multibyte string
mbmaxlen
max. length for multibyte string

Not all keys may be present, particularly dir.

Non-standard.

get_host_info()

Returns a string that represents the MySQL client library version. Non-standard.

get_proto_info()

Returns an unsigned integer representing the protocol version used by the current connection. Non-standard.

get_server_info()

Returns a string that represents the server version number. Non-standard.

info()

Retrieves a string providing information about the most recently executed query. Non-standard. Use messages or Cursor.messages.

insert_id()

Returns the ID generated for an AUTO_INCREMENT column by the previous query. Use this function after you have performed an INSERT query into a table that contains an AUTO_INCREMENT field.

Note that this returns 0 if the previous query does not generate an AUTO_INCREMENT value. If you need to save the value for later, be sure to call this immediately after the query that generates the value.

The ID is updated after INSERT and UPDATE statements that generate an AUTO_INCREMENT value or that set a column value to LAST_INSERT_ID(expr). See section 6.3.5.2 Miscellaneous Functions in the MySQL documentation.

Also note that the value of the SQL LAST_INSERT_ID() function always contains the most recently generated AUTO_INCREMENT value, and is not reset between queries because the value of that function is maintained in the server.

kill()

Asks the server to kill the thread specified by pid. Non-standard.

next_result()

If more query results exist, next_result() reads the next query results and returns the status back to application.

After calling next_result() the state of the connection is as if you had called query() for the next query. This means that you can now call store_result(), warning_count(), affected_rows() , and so forth.

Returns 0 if there are more results; -1 if there are no more results

Non-standard.

open

True if connection is open

ping()

Checks whether or not the connection to the server is working. If it has gone down, an automatic reconnection is attempted.

This function can be used by clients that remain idle for a long while, to check whether or not the server has closed the connection and reconnect if necessary.

New in 1.2.2: Accepts an optional reconnect parameter. If True, then the client will attempt reconnection. Note that this setting is persistent. By default, this is on in MySQL<5.0.3, and off thereafter.

Non-standard. You should assume that ping() performs an implicit rollback; use only when starting a new transaction. You have been warned.

port

TCP/IP port of the server connection

query()

Execute a query. store_result() or use_result() will get the result set, if any. Non-standard. Use cursor() to create a cursor, then cursor.execute().

read_query_result()

Read result of query sent by send_query().

rollback()

Rolls backs the current transaction

select_db()

Causes the database specified by db to become the default (current) database on the connection specified by mysql. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.

Fails unless the connected user can be authenticated as having permission to use the database.

Non-standard.

send_query()

Send a query. Same to query() except not wait response.

Use read_query_result() before calling store_result() or use_result()

server_capabilities

Capabilities of server; consult MySQLdb.constants.CLIENT

set_character_set()

Sets the default character set for the current connection. Non-standard.

set_server_option()

set_server_option(option) – Enables or disables an option for the connection.

Non-standard.

shutdown()

Asks the database server to shut down. The connected user must have shutdown privileges. Non-standard.

sqlstate()

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. ‘00000’ means “no error.” The values are specified by ANSI SQL and ODBC. For a list of possible values, see section 23 Error Handling in MySQL in the MySQL Manual.

Note that not all MySQL errors are yet mapped to SQLSTATE’s. The value ‘HY000’ (general error) is used for unmapped errors.

Non-standard.

stat()

Returns a character string containing information similar to that provided by the mysqladmin status command. This includes uptime in seconds and the number of running threads, questions, reloads, and open tables. Non-standard.

store_result()

Returns a result object acquired by mysql_store_result (results stored in the client). If no results are available, None is returned. Non-standard.

string_literal()

string_literal(obj) – converts object obj into a SQL string literal. This means, any special SQL characters are escaped, and it is enclosed within single quotes. In other words, it performs:

“’%s’” % escape_string(str(obj))

Use connection.string_literal(obj), if you use it at all. _mysql.string_literal(obj) cannot handle character sets.

thread_id()

Returns the thread ID of the current connection. This value can be used as an argument to kill() to kill the thread.

If the connection is lost and you reconnect with ping(), the thread ID will change. This means you should not get the thread ID and store it for later. You should get it when you need it.

Non-standard.

use_result()

Returns a result object acquired by mysql_use_result (results stored in the server). If no results are available, None is returned. Non-standard.

warning_count()

Returns the number of warnings generated during execution of the previous SQL statement.

Non-standard.

_mysql.debug()

Does a DBUG_PUSH with the given string. mysql_debug() uses the Fred Fish debug library. To use this function, you must compile the client library to support debugging.

_mysql.escape()

escape(obj, dict) – escape any special characters in object obj using mapping dict to provide quoting functions for each type. Returns a SQL literal string.

_mysql.escape_dict()

escape_sequence(d, dict) – escape any special characters in dictionary d using mapping dict to provide quoting functions for each type. Returns a dictionary of escaped items.

_mysql.escape_sequence()

escape_sequence(seq, dict) – escape any special characters in sequence seq using mapping dict to provide quoting functions for each type. Returns a tuple of escaped items.

_mysql.escape_string()

escape_string(s) – quote any SQL-interpreted characters in string s.

Use connection.escape_string(s), if you use it at all. _mysql.escape_string(s) cannot handle character sets. You are probably better off using connection.escape(o) instead, since it will escape entire sequences as well as strings.

_mysql.get_client_info()

get_client_info() – Returns a string that represents the client library version.

class _mysql.result

Bases: object

result(connection, use=0, converter={}) – Result set from a query.

Creating instances of this class directly is an excellent way to shoot yourself in the foot. If using _mysql.connection directly, use connection.store_result() or connection.use_result() instead. If using MySQLdb.Connection, this is done by the cursor class. Just forget you ever saw this. Forget... FOR-GET...

converter

Type conversion mapping

data_seek()

data_seek(n) – seek to row n of result set

describe()

Returns the sequence of 7-tuples required by the DB-API for the Cursor.description attribute.

fetch_row()

fetch_row([maxrows, how]) – Fetches up to maxrows as a tuple. The rows are formatted according to how:

0 – tuples (default) 1 – dictionaries, key=column or table.column if duplicated 2 – dictionaries, key=table.column
field_flags()

Returns a tuple of field flags, one for each column in the result.

has_next

Has next result

num_fields()

Returns the number of fields (column) in the result.

num_rows()

Returns the number of rows in the result set. Note that if use=1, this will not return a valid value until the entire result set has been read.

row_seek()

row_seek(n) – seek by offset n rows of result set

row_tell()

row_tell() – return the current row number of the result set.

_mysql.server_end()

Shut down embedded server. If not using an embedded server, this does nothing.

_mysql.server_init()

Initialize embedded server. If this client is not linked against the embedded server library, this function does nothing.

args – sequence of command-line arguments groups – sequence of groups to use in defaults files

_mysql.string_literal()

string_literal(obj) – converts object obj into a SQL string literal. This means, any special SQL characters are escaped, and it is enclosed within single quotes. In other words, it performs:

“’%s’” % escape_string(str(obj))

Use connection.string_literal(obj), if you use it at all. _mysql.string_literal(obj) cannot handle character sets.

_mysql.thread_safe()

Indicates whether the client is compiled as thread-safe.