.. 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
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
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):
"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):
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
