- The change in :ticket:`2721`, which is that the ``deferrable`` keyword

of :class:`.ForeignKeyConstraint` is silently ignored on the MySQL
backend, will be reverted as of 0.9; this keyword will now render again, raising
errors on MySQL as it is not understood - the same behavior will also
apply to the ``initially`` keyword.  In 0.8, the keywords will remain
ignored but a warning is emitted.   Additionally, the ``match`` keyword
now raises a :class:`.CompileError` on 0.9 and emits a warning on 0.8;
this keyword is not only silently ignored by MySQL but also breaks
the ON UPDATE/ON DELETE options.

To use a :class:`.ForeignKeyConstraint`
that does not render or renders differently on MySQL, use a custom
compilation option.  An example of this usage has been added to the
documentation, see :ref:`mysql_foreign_keys`.
[ticket:2721] [ticket:2839]

diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index 054227bd722709be4da0d2437d57bfaeb521819e..7a3909a9a2c4c8cec7b8af5aacbf99056f90412a 100644 (file)
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -10,6 +10,26 @@
 .. changelog::
     :version: 0.8.3
 
+    .. change::
+        :tags: bug, mysql
+        :tickets: 2721, 2839
+        :versions: 0.9.0
+
+        The change in :ticket:`2721`, which is that the ``deferrable`` keyword
+        of :class:`.ForeignKeyConstraint` is silently ignored on the MySQL
+        backend, will be reverted as of 0.9; this keyword will now render again, raising
+        errors on MySQL as it is not understood - the same behavior will also
+        apply to the ``initially`` keyword.  In 0.8, the keywords will remain
+        ignored but a warning is emitted.   Additionally, the ``match`` keyword
+        now raises a :class:`.CompileError` on 0.9 and emits a warning on 0.8;
+        this keyword is not only silently ignored by MySQL but also breaks
+        the ON UPDATE/ON DELETE options.
+
+        To use a :class:`.ForeignKeyConstraint`
+        that does not render or renders differently on MySQL, use a custom
+        compilation option.  An example of this usage has been added to the
+        documentation, see :ref:`mysql_foreign_keys`.
+
     .. change::
         :tags: bug, sql
         :tickets: 2825

diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index d0f654fe2f3727799dc7c0b1a09ec6303466d4fb..445355e9f7fb2fc7ad5e9c92c0462b40f640d852 100644 (file)
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -265,6 +265,41 @@ http://dev.mysql.com/doc/refman/5.0/en/create-index.html
 
 http://dev.mysql.com/doc/refman/5.0/en/create-table.html
 
+.. _mysql_foreign_keys:
+
+MySQL Foreign Key Options
+-------------------------
+
+MySQL does not support the foreign key arguments "DEFERRABLE", "INITIALLY",
+or "MATCH".  Using the ``deferrable`` or ``initially`` keyword argument with
+:class:`.ForeignKeyConstraint` or :class:`.ForeignKey` will have the effect of these keywords being
+rendered in a DDL expression, which will then raise an error on MySQL.
+In order to use these keywords on a foreign key while having them ignored
+on a MySQL backend, use a custom compile rule::
+
+    from sqlalchemy.ext.compiler import compiles
+    from sqlalchemy.schema import ForeignKeyConstraint
+
+    @compiles(ForeignKeyConstraint, "mysql")
+    def process(element, compiler, **kw):
+        element.deferrable = element.initially = None
+        return compiler.visit_foreign_key_constraint(element, **kw)
+
+.. versionchanged:: 0.9.0 - the MySQL backend no longer silently ignores
+   the ``deferrable`` or ``initially`` keyword arguments of :class:`.ForeignKeyConstraint`
+   and :class:`.ForeignKey`.
+
+The "MATCH" keyword is in fact more insidious, and is explicitly disallowed
+by SQLAlchemy in conjunction with the MySQL backend.  This argument is silently
+ignored by MySQL, but in addition has the effect of ON UPDATE and ON DELETE options
+also being ignored by the backend.   Therefore MATCH should never be used with the
+MySQL backend; as is the case with DEFERRABLE and INITIALLY, custom compilation
+rules can be used to correct a MySQL ForeignKeyConstraint at DDL definition time.
+
+.. versionadded:: 0.9.0 - the MySQL backend will raise a :class:`.CompileError`
+   when the ``match`` keyword is used with :class:`.ForeignKeyConstraint`
+   or :class:`.ForeignKey`.
+
 """
 
 import datetime
@@ -1612,7 +1647,11 @@ class MySQLDDLCompiler(compiler.DDLCompiler):
                     (self.preparer.format_table(constraint.table),
                     qual, const)
 
-    def define_constraint_deferrability(self, constraint):
+    def define_constraint_match(self, constraint):
+        if constraint.match is not None:
+            raise exc.CompileError(
+                    "MySQL ignores the 'MATCH' keyword while at the same time "
+                    "causes ON UPDATE/ON DELETE clauses to be ignored.")
         return ""
 
 class MySQLTypeCompiler(compiler.GenericTypeCompiler):

diff --git a/test/dialect/mysql/test_compiler.py b/test/dialect/mysql/test_compiler.py
index d1488ed330bd23522a1e23afa6e30d4a5949c915..a50c6a90172b76d30c6265ff2f500abfe9e396d1 100644 (file)
--- a/test/dialect/mysql/test_compiler.py
+++ b/test/dialect/mysql/test_compiler.py
@@ -104,17 +104,31 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             "CREATE INDEX bar ON foo (x > 5)"
         )
 
-    def test_skip_deferrable_kw(self):
+    def test_deferrable_initially_kw_not_ignored(self):
         m = MetaData()
         t1 = Table('t1', m, Column('id', Integer, primary_key=True))
         t2 = Table('t2', m, Column('id', Integer,
-                        ForeignKey('t1.id', deferrable=True),
+                        ForeignKey('t1.id', deferrable=True, initially="XYZ"),
                             primary_key=True))
 
         self.assert_compile(
             schema.CreateTable(t2),
             "CREATE TABLE t2 (id INTEGER NOT NULL, "
-            "PRIMARY KEY (id), FOREIGN KEY(id) REFERENCES t1 (id))"
+            "PRIMARY KEY (id), FOREIGN KEY(id) REFERENCES t1 (id) DEFERRABLE INITIALLY XYZ)"
+        )
+
+    def test_match_kw_raises(self):
+        m = MetaData()
+        t1 = Table('t1', m, Column('id', Integer, primary_key=True))
+        t2 = Table('t2', m, Column('id', Integer,
+                        ForeignKey('t1.id', match="XYZ"),
+                            primary_key=True))
+
+        assert_raises_message(
+            exc.CompileError,
+            "MySQL ignores the 'MATCH' keyword while at the same time causes "
+            "ON UPDATE/ON DELETE clauses to be ignored.",
+            schema.CreateTable(t2).compile, dialect=mysql.dialect()
         )
 
 class SQLTest(fixtures.TestBase, AssertsCompiledSQL):