diff --git a/core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php b/core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php
index d78cf48..edbcf2f 100644
--- a/core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php
+++ b/core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php
@@ -582,6 +582,9 @@ public function dropTable($table) {
       return FALSE;
     }
 
+    // Use CASCADE to ensure table deletion even if the table is referenced by a
+    // foreign key on another table. This is required in particular by test
+    // clean-up methods which may delete tables in any order.
     $this->connection->query('DROP TABLE {' . $table . '} CASCADE');
     $this->resetTableInformation($table);
     return TRUE;
diff --git a/core/lib/Drupal/Core/Database/Schema.php b/core/lib/Drupal/Core/Database/Schema.php
index 7e8ea41..20295c3 100644
--- a/core/lib/Drupal/Core/Database/Schema.php
+++ b/core/lib/Drupal/Core/Database/Schema.php
@@ -439,6 +439,8 @@ public function foreignKeyExists($table, $name) {}
    * @return true|null
    *   TRUE if the foreign key was created, NULL if the database does not
    *   support foreign keys.
+   *
+   * @see hook_schema()
    */
   public function addForeignKey($table, $name, array $fields) {
     if (!method_exists($this, 'createForeignKeySql')) {
diff --git a/core/lib/Drupal/Core/Database/database.api.php b/core/lib/Drupal/Core/Database/database.api.php
index 45a5618..9d0e6e3 100644
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
@@ -309,8 +309,12 @@
  *    specification). Each specification is an array containing the name of
  *    the referenced table ('table'), and an array of column mappings
  *    ('columns'). Column mappings are defined by key pairs ('source_column' =>
- *    'referenced_column'). This key is for documentation purposes only; foreign
- *    keys are not created in the database, nor are they enforced by Drupal.
+ *    'referenced_column'). The specification may also include 'on update' and
+ *    'on delete'. If both of these are set to one of "no action", "restrict",
+ *    "cascade", "set null", or "set default", then the foreign key will be
+ *    created in the database if the database supports foreign keys. Otherwise,
+ *    this key is for documentation purposes only; foreign keys will not be
+ *    created in the database, nor be enforced by Drupal.
  *  - 'indexes':  An associative array of indexes ('indexname' =>
  *    specification). Each specification is an array of one or more
  *    key column specifiers (see below) that form an index on the
@@ -360,16 +364,18 @@
  *   'unique keys' => array(
  *     'vid' => array('vid'),
  *   ),
- *   // For documentation purposes only; foreign keys are not created in the
- *   // database.
  *   'foreign keys' => array(
+ *     // This foreign key is for documentation purposes only.
  *     'node_revision' => array(
  *       'table' => 'node_field_revision',
  *       'columns' => array('vid' => 'vid'),
  *      ),
+ *     // This foreign key is created in supporting databases.
  *     'node_author' => array(
  *       'table' => 'users',
  *       'columns' => array('uid' => 'uid'),
+ *       'on update' => 'cascade',
+ *       'on delete' => 'set null',
  *      ),
  *    ),
  *   'primary key' => array('nid'),
@@ -472,9 +478,7 @@ function hook_query_TAG_alter(Drupal\Core\Database\Query\AlterableInterface $que
  * creation and alteration of the supported database engines.
  *
  * See the Schema API Handbook at https://www.drupal.org/node/146843 for details
- * on schema definition structures. Note that foreign key definitions are for
- * documentation purposes only; foreign keys are not created in the database,
- * nor are they enforced by Drupal.
+ * on schema definition structures.
  *
  * @return array
  *   A schema definition structure array. For each element of the
@@ -524,16 +528,18 @@ function hook_schema() {
       'nid_vid' => ['nid', 'vid'],
       'vid'     => ['vid'],
     ],
-    // For documentation purposes only; foreign keys are not created in the
-    // database.
     'foreign keys' => [
+      // This foreign key is for documentation purposes only.
       'node_revision' => [
         'table' => 'node_field_revision',
         'columns' => ['vid' => 'vid'],
       ],
+      // This foreign key is created in supporting databases.
       'node_author' => [
         'table' => 'users',
         'columns' => ['uid' => 'uid'],
+        'on update' => 'cascade',
+        'on delete' => 'set null',
       ],
     ],
     'primary key' => ['nid'],