diff options
| -rw-r--r-- | doc/build/dialects/mysql.rst | 76 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/base.py | 45 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/gaerdbms.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/mysqlconnector.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/mysqldb.py | 20 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/oursql.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/pymysql.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/pyodbc.py | 13 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/zxjdbc.py | 3 |
9 files changed, 117 insertions, 59 deletions
diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst index de71a99ac..33a0d783b 100644 --- a/doc/build/dialects/mysql.rst +++ b/doc/build/dialects/mysql.rst @@ -25,146 +25,141 @@ construction arguments, are as follows: .. autoclass:: BIGINT :members: __init__ - + .. autoclass:: BINARY :members: __init__ - + .. autoclass:: BIT :members: __init__ - + .. autoclass:: BLOB :members: __init__ - + .. autoclass:: BOOLEAN :members: __init__ - + .. autoclass:: CHAR :members: __init__ - + .. autoclass:: DATE :members: __init__ - + .. autoclass:: DATETIME :members: __init__ - + .. autoclass:: DECIMAL :members: __init__ - + .. autoclass:: DOUBLE :members: __init__ - + .. autoclass:: ENUM :members: __init__ - + .. autoclass:: FLOAT :members: __init__ - + .. autoclass:: INTEGER :members: __init__ - + .. autoclass:: LONGBLOB :members: __init__ - + .. autoclass:: LONGTEXT :members: __init__ - + .. autoclass:: MEDIUMBLOB :members: __init__ - + .. autoclass:: MEDIUMINT :members: __init__ - + .. autoclass:: MEDIUMTEXT :members: __init__ - + .. autoclass:: NCHAR :members: __init__ - + .. autoclass:: NUMERIC :members: __init__ - + .. autoclass:: NVARCHAR :members: __init__ - + .. autoclass:: REAL :members: __init__ - + .. autoclass:: SET :members: __init__ - + .. autoclass:: SMALLINT :members: __init__ - + .. autoclass:: TEXT :members: __init__ - + .. autoclass:: TIME :members: __init__ - + .. autoclass:: TIMESTAMP :members: __init__ - + .. autoclass:: TINYBLOB :members: __init__ - + .. autoclass:: TINYINT :members: __init__ - + .. autoclass:: TINYTEXT :members: __init__ - + .. autoclass:: VARBINARY :members: __init__ - + .. autoclass:: VARCHAR :members: __init__ - + .. autoclass:: YEAR :members: __init__ - + MySQL-Python -------------------- .. automodule:: sqlalchemy.dialects.mysql.mysqldb -OurSQL --------------- - -.. automodule:: sqlalchemy.dialects.mysql.oursql - pymysql ------------- @@ -180,6 +175,11 @@ cymysql .. automodule:: sqlalchemy.dialects.mysql.cymysql +OurSQL +-------------- + +.. automodule:: sqlalchemy.dialects.mysql.oursql + Google App Engine ----------------------- diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 5647c38f2..8727154f1 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -146,6 +146,49 @@ multi-column key for some storage engines:: Column('id', Integer, primary_key=True) ) +.. _mysql_unicode: + +Unicode +------- + +Most MySQL DBAPIs offer the option to set the client character set for +a connection. This is typically delivered using the ``charset`` parameter +in the URL, such as:: + + e = create_engine("mysql+pymysql://scott:tiger@localhost/\ +test?charset=utf8") + +Whether or not the DBAPI handles the job of encoding and decoding is determined +by passing the ``use_unicode`` parameter. For example, to disable +unicode conversion by the DBAPI and let SQLAlchemy handle it:: + + e = create_engine("mysql+pymysql://scott:tiger@localhost/\ +test?charset=utf8&use_uncode=0") + +The encoding used for Unicode has traditionally been ``'utf8'``. However, +for MySQL versions 5.5.3 on forward, a new MySQL-specific encoding +``'utf8mb4'`` has been introduced. The rationale for this new encoding +is due to the fact that MySQL's utf-8 encoding only supports +codepoints up to three bytes instead of four. Therefore, +when communicating with a MySQL database +that includes codepoints more than three bytes in size, +this new charset must be used, as in:: + + e = create_engine("mysql+pymysql://scott:tiger@localhost/\ +test?charset=utf8mb4") + +In order to use ``utf8mb4`` encoding, changes to +the MySQL schema and/or server configuration may be required - see the +MySQL documentation below for more information. + +.. seealso:: + + `The utf8mb4 Character Set \ +<http://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html>`_ + + :ref:`mysqldb_unicode` - MySQL-Python connection strings, which are + also equivalent on other MySQL DBAPIs. + Ansi Quoting Style ------------------ @@ -3308,7 +3351,7 @@ class _DecodingRowProxy(object): def __init__(self, rowproxy, charset): self.rowproxy = rowproxy - self.charset = self._encoding_compat.get(charset, charset) + self.charset = charset #self._encoding_compat.get(charset, charset) def __getitem__(self, index): item = self.rowproxy[index] diff --git a/lib/sqlalchemy/dialects/mysql/gaerdbms.py b/lib/sqlalchemy/dialects/mysql/gaerdbms.py index bbb6a9868..58b70737f 100644 --- a/lib/sqlalchemy/dialects/mysql/gaerdbms.py +++ b/lib/sqlalchemy/dialects/mysql/gaerdbms.py @@ -22,7 +22,7 @@ developers-guide Cloud SQL now recommends creating connections via the mysql dialect using the URL format - `mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename>` + ``mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename>`` Pooling diff --git a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py index 7a57705af..97fd0ccdf 100644 --- a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py +++ b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py @@ -14,6 +14,12 @@ :url: http://dev.mysql.com/downloads/connector/python/ +Unicode +------- + +Please see :ref:`mysql_unicode` for background on enabling charset support +with mysql-connector. + """ from .base import (MySQLDialect, MySQLExecutionContext, diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py index a65f69622..c61b09846 100644 --- a/lib/sqlalchemy/dialects/mysql/mysqldb.py +++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py @@ -13,6 +13,7 @@ :connectstring: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname> :url: http://sourceforge.net/projects/mysql-python +.. _mysqldb_unicode: Unicode ------- @@ -22,26 +23,23 @@ to handle non-ASCII characters correctly. When this parameter is passed, MySQLdb will also implicitly set the "use_unicode" flag to true, which means that it will return Python unicode objects instead of bytestrings. However, SQLAlchemy's decode process, when C extensions are enabled, -is orders of magnitude faster than that of MySQLdb as it does not call into +is dramatically faster than that of MySQLdb as it does not call into Python functions to do so. Therefore, the **recommended URL to use for unicode** will include both charset and use_unicode=0:: create_engine("mysql+mysqldb://user:pass@host/dbname?charset=utf8&use_unicode=0") -For MySQL versions 5.5.3 and MySQLdb version 1.2.3 forward, the special -MySQL-specific encoding 'utf8mb4' is now recommended:: +The ``'utf8'`` charset on MySQL only supports **up to three-byte codepoints**, +and not four-byte codepoints as normally supported by utf8. In order to +support all unicode codepoints, MySQL versions 5.5.3 and above +provide a MySQL-specific encoding ``'utf8mb4'``, which supports +codepoints up to four bytes in size:: create_engine("mysql+mysqldb://user:pass@host/dbname?charset=utf8mb4&use_unicode=0") -The 'utf8' encoding may still be used, however MySQL will only support -unicode characters within the first three of four possible bytes: -no (💩 or 😻) note that in order to use utf8mb4 fully, changes to -the MySQL schema and/or server configuration may be required. -See also: `The utf8mb4 character set -<http://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html>_`. +.. seealso:: -As of this writing, MySQLdb only runs on Python 2. It is not known how -MySQLdb behaves on Python 3 as far as unicode decoding. + :ref:`mysql_unicode` - Includes background on the ``'utf8mb4'`` character set. Known Issues diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py index ab6585abd..7f35e63be 100644 --- a/lib/sqlalchemy/dialects/mysql/oursql.py +++ b/lib/sqlalchemy/dialects/mysql/oursql.py @@ -32,6 +32,11 @@ defaults to, there is a separate parameter:: # use latin1 as the connection charset; all strings come back as unicode create_engine('mysql+oursql:///mydb?charset=latin1') + +.. seealso:: + + :ref:`mysql_unicode` - includes background on the ``'utf8'`` and ``'utf8mb4'`` charsets. + """ import re diff --git a/lib/sqlalchemy/dialects/mysql/pymysql.py b/lib/sqlalchemy/dialects/mysql/pymysql.py index ab7519d4c..46a40936e 100644 --- a/lib/sqlalchemy/dialects/mysql/pymysql.py +++ b/lib/sqlalchemy/dialects/mysql/pymysql.py @@ -14,6 +14,12 @@ [?<options>] :url: http://code.google.com/p/pymysql/ +Unicode +------- + +Please see :ref:`mysql_unicode` for background on enabling charset support +with PyMySQL. + MySQL-Python Compatibility -------------------------- diff --git a/lib/sqlalchemy/dialects/mysql/pyodbc.py b/lib/sqlalchemy/dialects/mysql/pyodbc.py index 08b339299..b544f0584 100644 --- a/lib/sqlalchemy/dialects/mysql/pyodbc.py +++ b/lib/sqlalchemy/dialects/mysql/pyodbc.py @@ -14,14 +14,11 @@ :connectstring: mysql+pyodbc://<username>:<password>@<dsnname> :url: http://pypi.python.org/pypi/pyodbc/ - -Limitations ------------ - -The mysql-pyodbc dialect is subject to unresolved character encoding issues -which exist within the current ODBC drivers available. -(see http://code.google.com/p/pyodbc/issues/detail?id=25). Consider usage -of OurSQL, MySQLdb, or MySQL-connector/Python. + .. note:: The PyODBC for MySQL dialect is not well supported, and + is subject to unresolved character encoding issues + which exist within the current ODBC drivers available. + (see http://code.google.com/p/pyodbc/issues/detail?id=25). + Other dialects for MySQL are recommended. """ diff --git a/lib/sqlalchemy/dialects/mysql/zxjdbc.py b/lib/sqlalchemy/dialects/mysql/zxjdbc.py index 9db969160..37b0b6309 100644 --- a/lib/sqlalchemy/dialects/mysql/zxjdbc.py +++ b/lib/sqlalchemy/dialects/mysql/zxjdbc.py @@ -14,6 +14,9 @@ <database> :driverurl: http://dev.mysql.com/downloads/connector/j/ + .. note:: Jython is not supported by current versions of SQLAlchemy. The + zxjdbc dialect should be considered as experimental. + Character Sets -------------- |