Support for foreign key constraints (#389)

[optilude]

This implements support for creating FOREIGN KEY ... REFERENCES declarations with ON DELETE and ON UPDATE triggers when defining associations, for all supported databases.

The basic syntax is:

var Task = this.sequelize.define('Task', { title: Sequelize.STRING })
  , User = this.sequelize.define('User', { username: Sequelize.STRING })

User.hasMany(Task, {onDelete: 'restrict'})

The same works for hasOne() and belongsTo(). Valid options are:

• onDelete -- set to e.g. restrict or cascade
• onUpdate -- set to e.g. restrict or cascade
• foreignKeyConstraint -- set to true to gain a REFERENCES declaration without either onDelete or onUpdate (that is, foreignKeyConstraint is implied if onDelete or onUpdate are set). This may be a helpful performance optimisation in some cases.

Some key implementation notes:

• Enabling constraints is opt-in: they are only created if one or more of the options above are used when defining an association.
• MySQL (with InnoDB tables) and Postgres support foreign key references by default. SQLite does not unless PRAGMA FOREIGN_KEYS=ON is issued. We do so when opening the database connection, unless explicitly disabled with a global option, to get parity across implementations. Note that just enabling this doesn't make any difference unless there are actual constraints in place.
• Only simple foreign keys are supported (because associations only support simple keys). This is the "80%" use case of course. Setting one of foreign key options in a situation where there is more than one primary key defined will cause the option to be ignored.
• SQL allows two ways to define foreign keys: "inline" (someId INTEGER REFERENCES someTable(id) ON DELETE CASCADE) or "standalone" (FOREIGN KEY(someId) REFERENCES someTable(id) ON DELETE CASCADE placed as a separate clause inside a CREATE TABLE statement). Since associations in sequelize create foreign key attributes the "inline" syntax is used, and attributesToSQL is taught how to add the relevant suffix to any "raw" attribute with the relevant metadata attached. This works for Postgres and SQLite, but MySQL ignores this syntax, requiring the "standalone" approach. For MySQL, we move the declaration to the end with a bit of string manipulation. This is analogous to how PRIMARY KEY is handled and allows this to be done without major refactoring.
• If we have foreign key constraints, the order in which tables are created matters: if foo has a foreign key to bar with a constraint, then bar has to exist before foo can be created. To make sure this happens, we use a topological sort of relationships (via the Toposort-class module, added as a dependency) to sequence calls to CREATE TABLE in sync(). This also necessitates sync() being serialised, but given it's an "on startup" operation that shouldn't be too much of an issue.
• A similar concern happens with dropAllTables(), but here we don't have enough information to sort the list. Instead, we do one of two things: for SQLite and MySQL, we temporarily disable constraint checking. For Postgres, we use DROP TABLE ... CASCADE to drop relevant constraints when required. (MySQL and SQLite only support the former and Postgres only supports the latter). This is blunt, but OK given that the function is attempting to drop all the tables.
• For other calls to dropTable() the caller is expected to sequence calls appropriately, or wrap the call in disableForeignKeyConstraints() and enableForeignKeyConstraints() (MySQL and SQLite; no-ops in Postgres) and/or pass {cascade: true} in options (Postgres; no-op in MySQL and SQLite).
• There are (passing) tests of the various dialect QueryGenerators and of cascade and restrict behaviour at the integration test level.
• I will add documentation (unless you'd prefer to do it yourself) if/once this PR is accepted, I just don't want to do it yet if there's going to be challenge.

[durango]

:+1 @sdepold and @mickhansen this has my vote (looked through the code. The styling seems OK, the only concern is that we're running synchronously in a few places that were previously async, but this I actually support within the PR's context).

@optilude nice job man, this is a huge win, I'd just like to get some other opinions in :)

[optilude]

@durango, glad you could look at it so quickly :)

The serialisation is a necessary evil (you can't create a table with a foreign key constraint to another table if the other table doesn't exist yet - see implementation note on the PR for more details), but it only happens during operations that are very unlikely to be on any sort of performance critical path: on sync() when we're creating new tables, and on dropAllTables().

If you like this one, you can thank me by merging #569 and then Sequelize will (hopefully) do everything I need for my project so I can go back to hacking on that one. ;)

[sdepold]

looks awesome. will take a closer look at it this evening. thanks for your work. best PR description ever :)

[sdepold]

typo "unless"

[sdepold]

rocksolid work. @mickhansen @janmeier any thoughts on this ? +1 from me

[janmeier]

This testcase seems to be duplicated thrice or did i miss something?

[optilude]

D'uh. It was a test copied from the MySQL implementation and then changed to remove MySQL-specific setting of the table engine, which of course left the three all the same. Corrected.

[janmeier]

Truly solid work! My comments are only very, very minor

I don't know what the others think, but given how well-written the description for this PR is, I would have no problem at all letting you write the docs as well! :)

[optilude]

@janmeier I'm happy to write some docs, but I don't understand how they're maintained/how to generate a test site. I need some meta-docs. ;)

[sdepold]

@optilude https://github.com/sequelize/sequelize-doc - its a mix of erb and markdown.

[leroy0211]

I would love to have some documentation about how exactly to use this extra "feature". Because I believe, but I don't know for sure that I can use this. I have sequelize 2.0.0-alpha2 installed, but I really don't know how to use this.

Any help or further documentation would be great!
Edit: I have got it working right now, but there is a slight problem

I have the next code:

var User = sequelize.define("User", { /* */ });
var Group = sequelize.define("Group", { /* */ });
var Apikey = sequelize.define("Apikey", { /* */ });

Group.hasMany(User);
User.hasMany(Apikey);

Somehow when trying to sync({force:true}) it want to try to drop the tables in this order:

1. Group
2. User
3. Apikey

This turns into the next error:

Cannot drop table Users because it is referenced by Apikeys

Sounds logical, because the apikeys table has a reference to User

The order of dropping should be:

1. Group
2. Apikey
3. User

Because the reference from the Apikeys table to the Users table must be removed first!

Also somehow Many-to-Many relations doesn't create Foreign Keys in the database. Al One-to-Many are executing perfectly!

[sdepold]

true. will add it later the day

Sascha Depold
Gesendet mit Sparrow (http://www.sparrowmailapp.com/?sig)

Am Donnerstag, 13. Juni 2013 um 23:04 schrieb leroybaeyens:

I would love to have some documentation about how exactly to use this extra "feature". Because I believe, but I don't know for sure that I can use this. I have sequelize 2.0.0-alpha2 installed, but I really don't know how to use this.
Any help or further documentation would be great!

—
Reply to this email directly or view it on GitHub (#595 (comment)).

[pward123]

It would be nice if we could do something like { onDelete: 'restrict', allowNull: false } to make the foreign key field non-nullable

[AdamPflug]

It seems like there is a fair amount of work going on to try to add the foreign key constraints at the same time that the tables are created. This means we need to try to determine what order to add the tables in, and then insert them synchronously in the right order. Wouldn't it be much easier to just create all the tables/fields, then alter them to add the constraints?

This also would fix a problem I'm having, which is that you cannot create unary relationship constraints the way we're currently doing it (even though it's perfectly valid SQL). For example:

User.hasMany(User, {as: 'Children', foreignKey: 'parentId', useJunctionTable: false, onDelete: 'cascade'})

Error: Cyclic dependency found. 'user' is dependent of itself.