From: Mike Bayer Date: Fri, 18 Oct 2013 19:00:42 +0000 (-0400) Subject: - The change in :ticket:`2721`, which is that the ``deferrable`` keyword X-Git-Tag: rel_0_8_3~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cf1ac72bca8b0bc28e09cdb4cdf052bcf82e5076;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - 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 2326d62161..a54f51a3e8 100644 --- 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 8ead8f148a..901849bb22 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -265,6 +265,45 @@ 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 ignored in a DDL expression along with a warning, however this behavior +**will change** in a future release. + +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.8.3 - the MySQL backend will emit a warning when the + the ``deferrable`` or ``initially`` keyword arguments of :class:`.ForeignKeyConstraint` + and :class:`.ForeignKey` are used. The arguments will no longer be + ignored in 0.9. + +The "MATCH" keyword is in fact more insidious, and in a future release will be +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.8.3 - the MySQL backend will emit a warning when + the ``match`` keyword is used with :class:`.ForeignKeyConstraint` + or :class:`.ForeignKey`. This will be a :class:`.CompileError` in 0.9. + """ import datetime @@ -1607,6 +1646,23 @@ class MySQLDDLCompiler(compiler.DDLCompiler): qual, const) def define_constraint_deferrability(self, constraint): + if constraint.deferrable is not None: + util.warn("The 'deferrable' keyword will no longer be ignored by the " + "MySQL backend in 0.9 - please adjust so that this keyword is " + "not used in conjunction with MySQL.") + if constraint.initially is not None: + util.warn("The 'initially' keyword will no longer be ignored by the " + "MySQL backend in 0.9 - please adjust so that this keyword is " + "not used in conjunction with MySQL.") + + return "" + + + def define_constraint_match(self, constraint): + if constraint.match is not None: + util.warn("MySQL ignores the 'MATCH' keyword while at the same time " + "causes ON UPDATE/ON DELETE clauses to be ignored - " + "this will be an exception in 0.9.") return "" class MySQLTypeCompiler(compiler.GenericTypeCompiler): diff --git a/test/dialect/mysql/test_compiler.py b/test/dialect/mysql/test_compiler.py index d1488ed330..8a242df824 100644 --- a/test/dialect/mysql/test_compiler.py +++ b/test/dialect/mysql/test_compiler.py @@ -104,17 +104,65 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL): "CREATE INDEX bar ON foo (x > 5)" ) - def test_skip_deferrable_kw(self): + def test_deferrable_emits_warning(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), primary_key=True)) - self.assert_compile( + assert_raises_message( + exc.SAWarning, + "The 'deferrable' keyword will no longer be ignored by the MySQL " + "backend in 0.9 - please adjust so that this keyword is not used in " + "conjunction with MySQL.", + schema.CreateTable(t2).compile, dialect=mysql.dialect() + ) + + @testing.emits_warning("The 'deferrable' keyword") + def go(): + self.assert_compile( + schema.CreateTable(t2), + "CREATE TABLE t2 (id INTEGER NOT NULL, " + "PRIMARY KEY (id), FOREIGN KEY(id) REFERENCES t1 (id))") + go() + + def test_initially_emits_warning(self): + m = MetaData() + t1 = Table('t1', m, Column('id', Integer, primary_key=True)) + t2 = Table('t2', m, Column('id', Integer, + ForeignKey('t1.id', initially="XYZ"), + primary_key=True)) + + assert_raises_message( + exc.SAWarning, + "The 'initially' keyword will no longer be ignored by the MySQL " + "backend in 0.9 - please adjust so that this keyword is not used " + "in conjunction with MySQL.", + schema.CreateTable(t2).compile, dialect=mysql.dialect() + ) + + @testing.emits_warning("The 'initially' keyword ") + def go(): + 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))") + go() + + + 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.SAWarning, + "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):