_mysql Module — MySQLdb 1.2.4b4 documentation

# _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.

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

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

  `server_capabilities`

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

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