feat(query-interface): support composite foreign keys (#12456)

Note: this commit was cherry-picked from a55c154

lib/dialects/abstract/query-generator.js

@@ -664,11 +664,15 @@ class QueryGenerator {
         break;
       case 'FOREIGN KEY':
         const references = options.references;
-        if (!references || !references.table || !references.field) {
+        if (!references || !references.table || !(references.field || references.fields)) {
           throw new Error('references object with table and field must be specified');
         }
         constraintName = this.quoteIdentifier(options.name || `${tableName}_${fieldsSqlString}_${references.table}_fk`);
-        const referencesSnippet = `${this.quoteTable(references.table)} (${this.quoteIdentifier(references.field)})`;
+        const quotedReferences =
+          typeof references.field !== 'undefined'
+            ? this.quoteIdentifier(references.field)
+            : references.fields.map(f => this.quoteIdentifier(f)).join(', ');
+        const referencesSnippet = `${this.quoteTable(references.table)} (${quotedReferences})`;
         constraintSnippet = `CONSTRAINT ${constraintName} `;
         constraintSnippet += `FOREIGN KEY (${fieldsSqlQuotedString}) REFERENCES ${referencesSnippet}`;
         if (options.onUpdate) {

lib/dialects/abstract/query-interface.js

@@ -679,6 +679,19 @@ class QueryInterface {
    *   onUpdate: 'cascade'
    * });
    *
+   * @example <caption>Composite Foreign Key</caption>
+   * queryInterface.addConstraint('TableName', {
+   *   fields: ['source_column_name', 'other_source_column_name'],
+   *   type: 'foreign key',
+   *   name: 'custom_fkey_constraint_name',
+   *   references: { //Required field
+   *     table: 'target_table_name',
+   *     fields: ['target_column_name', 'other_target_column_name']
+   *   },
+   *   onDelete: 'cascade',
+   *   onUpdate: 'cascade'
+   * });
+   *
    * @param {string} tableName                   Table name where you want to add a constraint
    * @param {object} options                     An object to define the constraint name, type etc
    * @param {string} options.type                Type of constraint. One of the values in available constraints(case insensitive)
@@ -689,6 +702,7 @@ class QueryInterface {
    * @param {object} [options.references]        Object specifying target table, column name to create foreign key constraint
    * @param {string} [options.references.table]  Target table name
    * @param {string} [options.references.field]  Target column name
+   * @param {string} [options.references.fields] Target column names for a composite primary key. Must match the order of fields in options.fields.
    *
    * @returns {Promise}
    */

test/unit/sql/add-constraint.test.js

@@ -157,6 +157,25 @@ if (current.dialect.supports.constraints.addConstraint) {
           });
         });
 
+        it('supports composite keys', () => {
+          expectsql(
+            sql.addConstraintQuery('myTable', {
+              type: 'foreign key',
+              fields: ['myColumn', 'anotherColumn'],
+              references: {
+                table: 'myOtherTable',
+                fields: ['id1', 'id2']
+              },
+              onUpdate: 'cascade',
+              onDelete: 'cascade'
+            }),
+            {
+              default:
+                'ALTER TABLE [myTable] ADD CONSTRAINT [myTable_myColumn_anotherColumn_myOtherTable_fk] FOREIGN KEY ([myColumn], [anotherColumn]) REFERENCES [myOtherTable] ([id1], [id2]) ON UPDATE CASCADE ON DELETE CASCADE;'
+            }
+          );
+        });
+
         it('uses onDelete, onUpdate', () => {
           expectsql(sql.addConstraintQuery('myTable', {
             type: 'foreign key',