mirror of
https://github.com/PyMySQL/mysqlclient.git
synced 2025-08-16 20:33:57 +08:00
Move the documentation around.
This commit is contained in:
adustman
127
mysql/doc/MySQLdb-FAQ.sgml
Normal file
127
mysql/doc/MySQLdb-FAQ.sgml
Normal file
@ -0,0 +1,127 @@
|
||||
<!doctype linuxdoc system>
|
||||
<article>
|
||||
<title>MySQLdb FAQ
|
||||
<author>Andy Dustman
|
||||
<date>$Id$
|
||||
<sect>Compiling <tt/_mysqlmodule.so/
|
||||
<P>Here are some common errors that happen during the build.
|
||||
This section covers UNIX/Linux problems only, as I don't do Windows.
|
||||
<tt/.so/ is a dynamically loading library on Linux and most other UNIX
|
||||
variants; a few use extensions other than <tt/.so/. Windows probably
|
||||
uses <tt/.dll/.
|
||||
<sect1>ImportError: libmysqlclient.so.6: cannot open shared object file:
|
||||
No such file or directory
|
||||
<P>
|
||||
You have dynamic MySQL libraries, and by default, your compiler links
|
||||
<tt/_mysqlmodule.so/ against these, but these are not on your loader path
|
||||
when you start Python.
|
||||
You have two basic options:
|
||||
<p>
|
||||
<enum>
|
||||
<item>
|
||||
Modify setup.py so that it links against the static library; see the comments.
|
||||
<item>
|
||||
Change your system environment so that the MySQL libraries are on
|
||||
your loader path. With Linux, you can modify <tt>/etc/ld.so.conf</tt> (see
|
||||
<tt/man ldconfig/ for more details) or you can add to or create the
|
||||
<tt/LD_LIBRARY_PATH/ environment variable before starting Python, i.e.
|
||||
<p><code>
|
||||
LD_LIBRARY_PATH=/path/to/mysql/libs python ... # Bourne-ish shell
|
||||
</code>
|
||||
</enum>
|
||||
<sect1>ImportError: ./_mysqlmodule.so: undefined symbol: PyLong_FromUnsignedLongLong
|
||||
<p>
|
||||
<tt/PyLong_FromUnsignedLongLong()/ first appears in Python 1.5.2, so you are
|
||||
linking against an earlier version. You may also have more than one version
|
||||
installed. Get Python 1.5.2 from your vendor or python.org.
|
||||
|
||||
<sect1>ImportError: ./_mysqlmodule.so: undefined symbol: uncompress
|
||||
<P>
|
||||
It seems that MySQL-3.23 client libraries require libz for gzip
|
||||
compression. setup.py should add this automatically.
|
||||
|
||||
<sect1>./_mysqlmodule.c:33: mysql.h: No such file or directory
|
||||
<P>The include path (-I) to your MySQL include files is wrong; modify
|
||||
setup.py. OR: You don't have the MySQL development stuff loaded. If you
|
||||
are using the Red Hat RPMs, you need the <tt/MySQL-devel/ RPM to compile
|
||||
<tt/_mysqlmodule.so/. However, if you link against the static MySQL
|
||||
libraries (see above), you can install <tt/_mysqlmodule.so/ on a system
|
||||
that does not have the MySQL client libraries (<tt/libmysqlclient/).
|
||||
|
||||
<sect1>I'm using Windows...
|
||||
<P>Say no more.
|
||||
<P>I don't use Windows. setup.py is supposed to work for building.
|
||||
There may also be a link to some user-contributed binaries on the web site.
|
||||
</sect1>
|
||||
<sect>
|
||||
Trouble with ZMySQLDA
|
||||
<p>What? ZMySQLDA never fails! Well, actually, I just don't have any
|
||||
good questions yet. Except: Install MySQLdb first, and then untar
|
||||
the ZMySQLDA source into your Zope home, and restart Zope.
|
||||
<sect>Using MySQLdb
|
||||
<p>
|
||||
MySQLdb is a
|
||||
<htmlurl url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
|
||||
name="Python Database API Specification 2.0"> database module, so you
|
||||
should be familiar with the spec. Deviations from the spec are documented in the
|
||||
<htmlurl url="http://dustman.net/andy/python/MySQLdb/doc/MySQLdb.html"
|
||||
name="MySQLdb documentation">.
|
||||
<sect1>What do I do if I am completely clueless?
|
||||
<p>Get a clue. Clues have been provided in the <tt/examples/ directory
|
||||
of the MySQLdb distribution.
|
||||
<sect1>No, I mean <em/really/ clueless!
|
||||
<p>Okay, it goes something like this:
|
||||
<enum>
|
||||
<item>
|
||||
Import MySQLdb.
|
||||
<item>
|
||||
Create a Connection object.
|
||||
<item>
|
||||
Create a Cursor object.
|
||||
<item>
|
||||
Execute your query on the Cursor object.
|
||||
<item>
|
||||
If your query returns rows, you can use the Cursor object to fetch them.
|
||||
<item>
|
||||
Rinse, lather, repeat.
|
||||
</enum>
|
||||
Example:
|
||||
<code>
|
||||
import MySQLdb
|
||||
db = MySQLdb.connect(db='mydb',user='myuser',passwd='mypasswd')
|
||||
c = db.cursor()
|
||||
c.execute(myquery)
|
||||
results = c.fetchall()
|
||||
</code>
|
||||
<sect1>But MySQL doesn't have cursors!
|
||||
<p>True enough. MySQLdb fakes it, though, because the spec requires it.
|
||||
<sect1>cursor.rollback() always fails!
|
||||
<p>MySQL now supports transactions using BDB tables.
|
||||
If your server doesn't support them, rollbacks will always fail, as they should,
|
||||
because it can't do what you asked.
|
||||
Even if your server does support them, rollbacks will fail if you
|
||||
modified any non-BDB tables.
|
||||
<p>OTOH, <tt/cursor.commit()/, which attempts to commit the transaction
|
||||
to the database, <em/does/ exist and always succeeds, because MySQL
|
||||
essentially is always in auto-commit mode.
|
||||
<sect1>How do I use some of the special MySQL features?
|
||||
<P>Short answer: Don't, if you can avoid it. Your program will not
|
||||
be portable to other databases.
|
||||
<P>Long answer: MySQLdb exports all symbols from _mysql. There are only
|
||||
a couple MySQL functions available this way, though. The Connection object
|
||||
does wrap nearly all of the various MySQL calls that use a <tt/MYSQL/
|
||||
argument (the connection handle in the C API). So let's say you want to
|
||||
use <tt/mysql_select_db(newdb)/. In MySQLdb, that's
|
||||
<tt/db.select_db(newdb)/ where <tt/db/ is your Connection object.
|
||||
<sect1>I still wanna use _mysql directly.
|
||||
<p>Well, it <tt/may/ be appropriate in some cirumstances.
|
||||
ZMySQLDA does this, because MySQLdb does a lot of type conversion that
|
||||
isn't necessary for Zope's purposes.
|
||||
<enum>
|
||||
<item>
|
||||
Read the MySQL docs, particularly the C API, for an overview.
|
||||
<item>
|
||||
Read the MySQLdb docs. This shows how the C API is transliterated
|
||||
into Python.
|
||||
</enum>
|
||||
</article>
|
||||
477
mysql/doc/MySQLdb.sgml
Normal file
477
mysql/doc/MySQLdb.sgml
Normal file
@ -0,0 +1,477 @@
|
||||
<!DOCTYPE linuxdoc system>
|
||||
<article>
|
||||
<title>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 (currently 7.0)
|
||||
for Intel. It should build without
|
||||
much trouble on most platforms by using the <tt/setup.py/ script.
|
||||
Supposedly it builds on MacOS X.
|
||||
Be aware that you need the Distutils package which comes with
|
||||
Python 2.0. If you don't have it (i.e. you have Python 1.5.2), you
|
||||
can find it over at <htmlurl url="http://www.python.org/" name="www.python.org">.
|
||||
<sect2>Windows (3.11, 95, 98, NT, 2000, CE, BSOD, XYZ, etc.)
|
||||
<p>
|
||||
Windows is <em/not/ a supported platform.
|
||||
However, the <tt/setup.py/ script
|
||||
reportedly gets the job done.
|
||||
There is probably a link on the web page for getting a precompiled
|
||||
Windows installer from someone or other.
|
||||
Be aware that this is a user-contributed package; the author
|
||||
cannot help you with compiling and running under Windows.
|
||||
<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 problem trying to insert <tt/TIME/
|
||||
values with fractional seconds. Values like 12:56:13.00 are
|
||||
returned as 344:13:00, apparently interpreting the original input
|
||||
as 12 days, 56 hours, 13 minutes, 0 seconds. (12 days and 56 hours
|
||||
is 344 hours.) To avoid this problem, use the <tt/DateTimeDelta/
|
||||
type.
|
||||
|
||||
<sect2>MySQL-3.23
|
||||
<p>
|
||||
MySQL-3.23 is presently in gamma (stable prerelease). Several API
|
||||
additions have been made so far. These will be incorporated into
|
||||
MySQLdb as work progresses. As of 3.23.30, transactions are supported
|
||||
in MySQL using BDB tables. MySQLdb (0.3.0 and up) detects the
|
||||
presence of BDB table support
|
||||
upon connection and will issue <tt/COMMIT/ and <tt/ROLLBACK/
|
||||
statements when appropriate. Note that MySQL operates in
|
||||
<tt/AUTOCOMMIT/ mode by default; you will have to issue SQL to
|
||||
change this.
|
||||
|
||||
<sect1>DateTime
|
||||
<p>If you have the <htmlurl
|
||||
url="http://www.lemburg.com/files/python/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.
|
||||
MySQLdb-0.2.2 and up include <tt/CompatMysqldb/, which is an adaptation
|
||||
of <tt/Mysqldb/ to <tt/_mysql/. It should be considered experimental.
|
||||
|
||||
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; alternate cursor class <tt>DictCursor</tt>
|
||||
provides a dictionary interface,
|
||||
keys are "<em/column/" or "<em/table.column/" if there are two columns
|
||||
with the same name; 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
|
||||
server can perform transactions; otherwise <tt>db.rollback()</tt>
|
||||
always fails
|
||||
<caption>Mysqldb to MySQLdb changes</tabular></table>
|
||||
|
||||
<sect1>Zope and ZMySQLDA
|
||||
<p>I wrote a <htmlurl url="http://dustman.net/andy/python/ZMySQLDA" name="ZMySQLDA"> for use with MySQLdb.
|
||||
<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://dustman.net/andy/python/MySQLdb/faq/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>Compatibility note: As of 0.3.0, the various fetch_rowXXX() cursor
|
||||
methods have been combined into a single fetch_row([n=1[,how=0]])
|
||||
method. See the built-in module documentation for more details.
|
||||
<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()</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_options()</tt> | <tt>_mysql.connect()</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_real_escape_string()</tt> | <tt>conn.escape_string()</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
|
||||
<htmlurl url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
|
||||
name="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.
|
||||
In addition, there are a few additional keywords that correspond
|
||||
to what you would pass <tt/mysql_options()/ before connecting. 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: <tt/MySQLdb.type_conv/
|
||||
|
||||
<tag>quote_conv</tag> Python type-to-literal conversion
|
||||
dictionary. Default: <tt/MySQLdb.quote_conv/
|
||||
|
||||
<tag>cursorclass</tag> cursor class that <tt/cursor()/ uses,
|
||||
unless overridden. Default: <tt/MySQLdb.Cursor/.
|
||||
|
||||
<tag>compress</tag> Enable protocol compression. Default: no compression.
|
||||
|
||||
<tag>connect_timeout</tag> Abort if connect is not completed within
|
||||
given number of seconds. Default: no timeout (?)
|
||||
|
||||
<tag>named_pipe</tag> Use a named pipe (Windows). Default: don't.
|
||||
|
||||
<tag>init_command</tag> Initial command to issue to server upon
|
||||
connection. Default: Nothing.
|
||||
|
||||
<tag>read_default_file</tag> MySQL configuration file to read; see
|
||||
the MySQL documentation for <tt/mysql_options()/.
|
||||
|
||||
<tag>read_default_group</tag> Default group to read; see the MySQL
|
||||
documentation for <tt/mysql_options()/.
|
||||
|
||||
<tag>unix_socket</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. As of MySQLdb version 0.2.0, this
|
||||
is set to 2, which means: Threads may share the module and connections.
|
||||
Cursors employ a mutex in the connection object to ensure that
|
||||
cursors do not use the connection at the same time. Generally,
|
||||
sharing a connection probably reduces performance; the MySQL
|
||||
server maintains a seperate thread for each connection.
|
||||
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.
|
||||
<P>As of MySQL-3.23, MySQL supports different character sets in the
|
||||
server, and a new quoting function, <tt/mysql_real_escape_string()/.
|
||||
This requires the string quoting function to be a method bound to
|
||||
the connection object. MySQLdb handles this for you automatically.
|
||||
However, if you feel the need to do something goofy with your strings,
|
||||
you will have to modify the dictionary after opening the connection.
|
||||
In practice, you should never have to worry about this.
|
||||
|
||||
</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 supports transactions
|
||||
as of version 3.23.15-alpha.</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.
|
||||
|
||||
Compatibility note: The older <ref id="MySQLmodule"> defines 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([cursorclass])</tag>
|
||||
MySQL does not support cursors; however, cursors are easily emulated.
|
||||
You can supply an alternative cursor class as an optional parameter.
|
||||
If this is not present, it defaults to the value
|
||||
given when creating the connection object, or the standard <tt/Cursor/
|
||||
class. Also see the additional supplied cursor classes in the
|
||||
<ref id="usage"> section.
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect1>Cursor Objects
|
||||
<p>
|
||||
<descrip>
|
||||
<tag>callproc()</tag>
|
||||
Not implemented.
|
||||
|
||||
<tag>close()</tag>
|
||||
Closes the cursor. Future operations raise <tt/ProgrammingError/.
|
||||
If you are using <ref id="SSCursor" name="server-side cursors">,
|
||||
it is very important to close the cursor when you are done with
|
||||
it and before creating a new one. Otherwise, deadlock may occur.
|
||||
|
||||
<tag/insert_id()/
|
||||
Returns the last <tt/AUTO_INCREMENT/ field value inserted
|
||||
into the database. (Non-standard)
|
||||
|
||||
<tag>nextset()</tag>
|
||||
Not implemented.
|
||||
|
||||
<tag>setinputsizes()</tag>
|
||||
Does nothing, successfully.
|
||||
|
||||
<tag>setoutputsizes()</tag>
|
||||
Does nothing, successfully.
|
||||
|
||||
</descrip>
|
||||
<sect>Using and extending<label id="usage">
|
||||
|
||||
<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://dustman.net/andy/python"
|
||||
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>BaseCursor</tag> The base class for Cursor objects.
|
||||
This does not raise Warnings.
|
||||
|
||||
<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><label id="SSCursor">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 that share connections. Note that creating the cursor
|
||||
causes it to acquire a lock on the connection object, and this is
|
||||
not released until the cursor is deleted or <tt/cursor.close()/.
|
||||
If you aren't careful about this, it can result in deadlock, which
|
||||
is bad.
|
||||
|
||||
<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,
|
||||
i.e., you are selecting from two tables that share column names,
|
||||
some of them will be rewritten as <em/table.column/.
|
||||
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.
|
||||
|
||||
<tag>DictCursor</tag> Like <tt/Cursor/ except it returns rows as
|
||||
dictionaries.
|
||||
|
||||
<tag>SSCursor</tag> A "server-side" cursor. Like <tt/Cursor/ but uses
|
||||
<tt/CursorUseResultMixIn/. Thread-safe, but not recommended for
|
||||
threaded applications which share connections.
|
||||
Use only if you are dealing with potentially large result sets.
|
||||
|
||||
<tag/SSDictCursor/ Like <tt/SSCursor/ except it returns rows as
|
||||
dictionaries.
|
||||
|
||||
<tag/XXXCursorNW/> Cursors with the "NW" suffix do not raise Warnings.
|
||||
|
||||
</descrip>
|
||||
<p>For an example of how to use these classes,
|
||||
read the code. If you need something more exotic than this,
|
||||
you will have to roll your own.
|
||||
</article>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user