diff --git a/mysql/MySQLdb.sgml b/mysql/MySQLdb.sgml new file mode 100644 index 0000000..2f09c4c --- /dev/null +++ b/mysql/MySQLdb.sgml @@ -0,0 +1,432 @@ + +
+MySQLdb: a Python interface for MySQL +<author>Andy Dustman +<date>$Id$ + +<abstract>MySQLdb is an thread-compatible interface to the popular +MySQL database server that provides the Python database API. + +<sect>Introduction + +<P>This module should be <ref id="MySQLmodule" name="mostly compatible"> +with an older interface +written by Joe Skinner and others. However, the older version is a) +not thread-friendly (database operations could cause all other threads +to block), b) written for MySQL 3.21 (does not compile against newer +versions without patches), c) apparently not actively +maintained. MySQLdb is a completely new module, distributed free of +charge under a license derived from the Python license. + +<p> +<sect1>Platforms +<p> +<sect2>Linux/UNIX +<p> +This module is developed on RedHat Linux 5.2 for Intel. It should build without +much trouble on most UNIX-like platforms by using the <tt/build.py/ script. +<sect2>Windows (3.11, 95, 98, NT, 2000, CE, BSOD, XYZ, etc.) +<p> +Windows is <em/not/ a supported platform. +However, the <tt/compile.py/ script +reportedly gets the job done, probably just on NT, maybe others. +<sect1>Python +<p> +MySQLdb requires Python 1.5.2. Earlier versions will not work, because +support for C <tt/long long/ is required by MySQL. If you have an +earlier version of Python, upgrade to 1.5.2 or beyond. + +<sect1>MySQL +<p> +<sect2>MySQL-3.22 +<p> +Only versions 3.22.32 and +up are guaranteed to work. Some older versions may work; +if you have an older version you should +seriously consider upgrading to get the bug fixes and particularly +the security updates. + +MySQL-3.22 seems to have a strange bug when handling TIME +columns. For this reason, there is presently no type converter for +TIME columns (the value is returned as a string). If you want to +experiment with this, the code which actives the type converter can be +easily commented in. + +<sect2>MySQL-3.23 +<p> +MySQLdb has only been lightly tested. +MySQL-3.23 is presently in alpha (unstable) release. Several API +additions have been made so far. These will be incorporated into +MySQLdb as work progresses. + +<sect1>DateTime +<p>If you have the <htmlurl +url="http://starship.skyport.net/~lemburg/mxDateTime.html" +name="DateTime"> module installed (recommended), MySQLdb will use +it for date-related objects. Otherwise, these will be returned to +Python as strings. You can also modify the type conversion +dictionaries to return these as other object classes, if you +prefer. + +<sect1>MySQLmodule<label id="MySQLmodule"> +<p> +MySQLmodule, the older MySQL interface by Joe Skinner and others, + is also a split C/Python +interface. <tt/MySQL/, the C portion, has an interface similar to +perl's DBI internally. In addition, there is Python portion, <tt/Mysqldb/, +which provides a DB API v1.0 interface, written by James Henstridge. + +In contrast, MySQLdb's C portion, <tt><ref id="_mysql"></tt>, is designed +to mimic the MySQL C API in an object-oriented way; you should not +expect to move from <tt/MySQL/ to <tt/_mysql/ without a fair amount of +work. <tt><ref id="MySQLdb"></tt> provides a DB API v2.0 interface, +which has some changes from the v1.0 interface. Things to watch out +for in particular: + +<table> +<tabular ca="foo"> +Operation | Mysqldb | MySQLdb +@ Connecting | <tt>db = Mysqldb.Mysqldb("db@host user pass")</tt> +| <tt>db = MySQLdb.connect(db='db', host='host', user='user', passwd='pass')</tt> +@ Implicit cursor | <tt>db.execute(SQL)</tt> | +implicit cursors dropped from DB API v2.0; always use <tt>c = db.cursor()</tt> +@ Fetch row as dictionary | <tt>c.fetchDict()</tt>, +keys are "<em/table.column/" | +not standard; <tt>MySQLDict.py</tt> provides a dictionary interface, +keys are "<em/column/"; use SQL <tt/AS/ to rename fields. +@ Transactions | <tt>db.commit()</tt> and <tt>db.rollback()</tt> +both exist and silently do nothing <ref id="rollback" name="(danger!)"> +| <tt>db.commit()</tt> and <tt>db.rollback()</tt> work if the MySQL +client library can perform transactions; otherwise <tt>db.rollback()</tt> +is not defined +<caption>Mysqldb to MySQLdb changes</tabular></table> + +<sect1>Zope and ZMySQLDA +<p>The distribution contains a patch to modify the +<htmlurl url="http://www.zope.org/" name="Zope"> +<htmlurl url="http://www.zope.org/Members/MikeP/ZMySQLDA" name="ZMySQLDA"> +to use MySQLdb instead of MySQLmodule. Read the instructions in +the patch. If that fails, read the FAQ. +<sect1>Documentation +<p>The web page documentation may be slightly ahead of the latest release +and may reflect features of the next release. +<sect1>FAQs +<p>A FAQ is available at +<htmlurl url="http://starship.python.net/crew/adustman/MySQLdb-FAQ.html">. +<sect>_mysql module<label id="_mysql"> +<P> +If you want to write applications which are portable across databases, +avoid using this module directly. <tt>_mysql</tt> provides an +interface which mostly implements the MySQL C API. For more +information, see the MySQL documentation. The documentation for this +module is intentionally weak because you probably should use the +higher-level <ref id="MySQLdb"> module. If you really need it, use the +standard MySQL docs and transliterate as necessary. +<p> +The C API has been wrapped in an object-oriented way. The only MySQL +data structures which are implemented are the <tt>MYSQL</tt> (database +connection handle) and <tt>MYSQL_RES</tt> (result handle) types. In +general, any function which takes <tt>MYSQL *mysql</tt> as an argument +is now a method of the connection object, and any function which takes +<tt>MYSQL_RES *result</tt> as an argument is a method of the result +object. Functions requiring none of the MySQL data structures are +implemented as functions in the module. Functions requiring one of the +other MySQL data structures are generally not implemented. Deprecated +functions are not implemented. In all cases, the <tt>mysql_</tt> +prefix is dropped from the name. Most of the <tt>conn</tt> methods +listed are also available as MySQLdb Connection object methods. Their +use is explicitly non-portable. +<table> +<tabular ca="MySQL C API foo foo function mapping"> + C API | <tt>_mysql</tt> +@ <tt>mysql_affected_rows()</tt> | <tt>conn.affected_rows()</tt> +@ <tt>mysql_close()</tt> | <tt>conn.close()</tt> +@ <tt>mysql_connect()</tt> | <tt>_mysql.connect()</tt> +@ <tt>mysql_data_seek()</tt> | <tt>result.data_seek()</tt> +@ <tt>mysql_debug()</tt> | <tt>_mysql.debug()</tt> +@ <tt>mysql_dump_debug_info</tt> | <tt>conn.dump_debug_info()</tt> +@ <tt>mysql_escape_string()</tt> | <tt>_mysql.escape_string()</tt> +@ <tt>mysql_fetch_row()</tt> | <tt>result.fetch_row()<newline> +result_fetch_row_as_dict()<newline> +result.fetch_rows()<newline> +result.fetch_rows_as_dict()<newline> +result.fetch_all_rows()<newline> +result.fetch_all_rows_as_dict()</tt> +@ <tt>mysql_get_client_info()</tt> | <tt>_mysql.get_client_info()</tt> +@ <tt>mysql_get_host_info()</tt> | <tt>conn.get_host_info()</tt> +@ <tt>mysql_get_proto_info()</tt> | <tt>conn.get_proto_info()</tt> +@ <tt>mysql_get_server_info()</tt> | <tt>conn.get_server_info()</tt> +@ <tt>mysql_info()</tt> | <tt>conn.info()</tt> +@ <tt>mysql_insert_id()</tt> | <tt>conn.insert_id()</tt> +@ <tt>mysql_list_dbs()</tt> | <tt>conn.list_dbs()</tt> +@ <tt>mysql_list_fields()</tt> | <tt>conn.list_fields()</tt> +@ <tt>mysql_list_processes()</tt> | <tt>conn.list_processes()</tt> +@ <tt>mysql_list_tables()</tt> | <tt>conn.list_tables()</tt> +@ <tt>mysql_num_fields()</tt> | <tt>result.num_fields()</tt> +@ <tt>mysql_num_rows()</tt> | <tt>result.num_rows()</tt> +@ <tt>mysql_ping()</tt> | <tt>conn.ping()</tt> +@ <tt>mysql_query()</tt> | <tt>conn.query()</tt> +@ <tt>mysql_real_connect()</tt> | <tt>_mysql.connect()</tt> +@ <tt>mysql_real_query()</tt> | <tt>conn.query()</tt> +@ <tt>mysql_row_seek()</tt> | <tt>result.row_seek()</tt> +@ <tt>mysql_row_tell()</tt> | <tt>result.row_tell()</tt> +@ <tt>mysql_select_db()</tt> | <tt>conn.select_db()</tt> +@ <tt>mysql_stat()</tt> | <tt>conn.stat()</tt> +@ <tt>mysql_store_result()</tt> | <tt>conn.store_result()</tt> +@ <tt>mysql_thread_id()</tt> | <tt>conn.thread_id()</tt> +@ <tt>mysql_use_result()</tt> | <tt>conn.use_result()</tt> +@ <tt>CLIENT_*</tt> | <tt>_mysql.CLIENT.*</tt> +@ <tt>CR_*</tt> | <tt>_mysql.CR.*</tt> +@ <tt>ER_*</tt> | <tt>_mysql.ER.*</tt> +@ <tt>FIELD_TYPE_*</tt> | <tt>_mysql.FIELD_TYPE.*</tt> +@ <tt>FLAG_*</tt> | <tt>_mysql.FLAG.*</tt> +<caption>MySQL C API function mapping +</tabular> +</table> +<sect>MySQLdb -- DB API interface<label id="MySQLdb"> +<p> +MySQLdb is a thin Python wrapper around <tt><ref id="_mysql"></tt> +which makes it compatible with the Python DB API interface (version +2). In reality, a fair amount of the code which implements the API is +in <tt>_mysql</tt> for the sake of efficiency. +<p> +The DB API specification should be your primary guide for using this +module. Only deviations from the spec and other database-dependent +things will be documented here. Note that all symbols from +<tt>_mysql</tt> are imported into this module. Mostly these are the +required exceptions, the constant classes, and a very few functions. +<sect1>Functions and attributes <P>Only a few top-level functions and +attributes are defined within MySQLdb. + +<descrip> +<tag><label id="connect()">connect(parameters...)</tag> Constructor + for creating a connection to the database. Returns a Connection + Object. Parameters are the same as for the MySQL C API. Note + that all parameters must be specified as keyword arguments! The + default value for each parameter is NULL or zero, as + appropriate. Consult the MySQL documentation for more + details. The important parameters are: + +<descrip> + <tag>host</tag> + name of host to connect to. Default: use local host + + <tag>user</tag> + user to authenticate as. Default: current effective user. + + <tag>passwd</tag> + password to authenticate with. Default: no password. + + <tag>db</tag> + database to use. Default: no default database. + + <tag>conv</tag> literal-to-Python type conversion dictionary. + Default: empty dictionary, no type conversion. + + <tag>quote_conv</tag> Python type-to-literal conversion + dictionary Default: empty dictionary, no type conversion. + +<tag>unix_pipe</tag> + location of UNIX socket. Default: use TCP. + +<tag>port</tag> + TCP port of MySQL server. Default: standard port (3306). +</descrip> + +<tag>apilevel</tag> + String constant stating the supported DB API level. '2.0' + +<tag>threadsafety</tag> Integer constant stating the level of thread + safety the interface supports. Set to 1, which means: Threads + may share the module, but not connections. This is the practice + recommended by the MySQL documentation. However, it should be + safe to share a connection between two threads provided only one + thread at a time uses it (i.e. a mutex is employed). Note that + this is only safe if the threads are using. mysql_store_result() + as opposed to mysql_use_result(). The latter is not recommended + for threaded applications. See the MySQL documentation for more + details. + +<tag>paramstyle</tag> String constant stating the type of parameter + marker formatting expected by the interface. Set to 'format' = + ANSI C printf format codes, e.g. '...WHERE name=%s'. If a + mapping object is used for conn.execute(), then the interface + actually uses 'pyformat' = Python extended format codes, + e.g. '...WHERE name=%(name)s'. However, the API does not + presently allow the specification of more than one style in + paramstyle. + + Compatibility note: The older MySQLmodule uses a similar + parameter scheme, but requires that quotes be placed around + format strings which will contain strings, dates, and similar + character data. This is not necessary for MySQLdb. It is + recommended that %s (and not '%s') be used for all parameters, + regardless of type. The interface performs all necessary + quoting. + +<tag><label id="type_conv">type_conv</tag> A dictionary mapping MySQL + types (from <TT>FIELD_TYPE.*</TT>) to callable Python objects + (usually functions) which convert from a string to the desired + type. This is initialized with reasonable defaults for most + types. When creating a Connection object, you can pass your own + type converter dictionary as a keyword parameter. Otherwise, it + uses a copy of <tt>type_conv</tt> which is safe to modify on a + per-connection basis. The dictionary includes some of the + factory functions from the <tt>DateTime</tt> module, if it is + available. Several non-standard types (<tt>SET, ENUM</tt>) are + returned as strings, which is how MySQL returns all + columns. Note: <tt>TIME</tt> columns are returned as strings + presently. This should be a temporary condition. + +<tag><label id="quote_conv">quote_conv</tag> A dictionary mapping + Python types (from the standard <tt>types</tt> module or + built-in function <tt>type()</tt> to MySQL literals. By + default, the value is treated as a string. When creating a + Connection object, you can pass your own quote converter + dictionary as a keyword parameter. + +</descrip> + +<sect1>Connection Objects +<P>Connection objects are returned by the <tt>connect()</tt> function. +<descrip> +<tag>commit()</tag> If the database supports transactions, this + commits the current transaction; otherwise this method + successfully does nothing. <footnote>MySQL does not presently + support transactions.</footnote> + +<tag><label id="rollback">rollback()</tag> If the + database supports transactions, this rolls back (cancels) the + current transaction; otherwise a <tt>NotSupportedError</tt> is + raised. This method is only defined if the MySQL client library + supports transactions. + +Compatibility note: The older <ref id="MySQLmodule"> does define this method, + which sucessfully does nothing. This is dangerous behavior, as a + successful rollback indicates that the current transaction was + backed out, which is not true, and fails to notify the + programmer that the database now needs to be cleaned up by other + means. + +<tag>cursor(parameters...)</tag> + MySQL does not support cursors; however, cursors are easily emulated. +</descrip> + +<sect1>Cursor Objects +<P>Cursor objects support an optional argument +<tt>name</tt>, which is pretty useless. While it is possible to +create Cursor objects with the class constructor, this is not +recommended. +<p> +<descrip> +<tag>callproc()</tag> + Not implemented. + +<tag>nextset()</tag> + Not implemented. + +<tag>setinputsizes()</tag> + Does nothing, successfully. + +<tag>setoutputsizes()</tag> + Does nothing, successfully. + +<tag><label id="executeXXX()">execute(query[,parameters]></tag> + +<tag>executemany(query,[,parameters])</tag> These methods work as + described in the API. The parameters are converted according to + the <ref id="quote_conv"> dictionary (see above). By default, + <tt>str()</tt> is used as the conversion function. This presents + a problem for the various date and time columns: + <tt>__str__</tt> for <tt>DateTime</tt> objects includes + fractional seconds, which MySQL (up to 3.22.32, at least), + considers illegal input, and so zeros the field. This may be + fixed in later MySQL releases. + +<tag>fetchone()</tag> + +<tag>fetchmany([n])</tag> + +<tag>fetchall()</tag> + These methods work as described in the API. + +<tag>format_DATE(d)</tag> + +<tag>format_TIME(d)</tag> + +<tag>format_TIMESTAMP(d)</tag> These functions all take a DateTime + object as input and return an appropriately formatted + string. They are intended for use with the <tt><ref + id="executeXXX()"></tt> methods. + +</descrip> +<sect>Using and extending + +<P>In general, it is probably wise to not directly interact with the +DB API except for small applicatons. Databases, even SQL databases, +vary widely in capabilities and may have non-standard features. The DB +API does a good job of providing a reasonably portable interface but +some methods are non-portable. Specifically, the parameters accepted +by <tt><ref id="connect()"></tt> are completely implementation-dependent. + +If you believe your application may need to run on several different +databases, the author recommends the following approach, based on +personal experience: Write a simplified API for your application which +implements the specific queries and operations your application needs +to perform. Implement this API as a base class which should be have +few database dependencies, and then derive a subclass from this which +implements the necessary dependencies. In this way, porting your +application to a new database should be a relatively simple matter of +creating a new subclass, assuming the new database is reasonably +standard. + +For an example of this, see the author's +<htmlurl url="http://starship.python.net/crew/adustman" +name="SQLDict module">, which allows standard queries to be +defined and accessed using an object which looks like a +dictionary, and reads/writes user-defined objects. + +Because MySQLdb's Connection and Cursor objects are written in Python, +you can easily derive your own subclasses. There are several Cursor +classes in MySQLdb: +<p> +<descrip> +<tag>CursorBase</tag> The base class for Cursor objects. + +<tag>CursorWarningMixIn</tag> Causes the Warning exception to be raised +on queries which produce warnings. + +<tag>CursorStoreResultMixIn</tag> Causes the Cursor to use the +<tt>mysql_store_result()</tt> function to get the query result. The +entire result set is stored on the client side. + +<tag>CursorUseResultMixIn</tag> Causes the cursor to use the +<tt>mysql_use_result()</tt> function to get the query result. The +result set is stored on the server side and is transferred row by row +using fetch operations. Not recommended, particularly for threaded +applications. + +<tag>CursorTupleRowsMixIn</tag> Causes the cursor to return rows +as a tuple of the column values. + +<tag>CursorDictRowsMixIn</tag> Causes the cursor to return rows +as a dictionary, where the keys are column names and the values +are column values. Note that if the column names are not unique, +some of them will be overwritten. This can be avoided by using +the SQL <tt>AS</TT> keyword. (This is yet-another reason not to use +<tt/*/ in SQL queries, particularly where <tt/JOIN/ is involved. + +<tag>Cursor</tag> The default cursor class. This class is composed +of <tt>CursorWarningMixIn, CursorStoreResultMixIn, CursorTupleRowsMixIn,</tt> +and <tt>BaseCursor</tt>, i.e. it raises <tt>Warning</tt>, uses +<tt>mysql_store_result()</tt>, and returns rows as tuples. +</descrip> +<p>For an example of how to use these classes, take a look at the +<tt>MySQLDict</tt> module, which comes with MySQLdb. +This operates as above, except that it +returns rows as dictionaries. + +</article> + + +