From 8576ca873d9a0e59a8736bbd7ed745835e875e0d Mon Sep 17 00:00:00 2001
From: David Kane <david@dkane.net>
Date: Mon, 16 Nov 2020 00:40:04 +0000
Subject: [PATCH] add possibility of compound foreign keys to docs

---
 docs/python-api.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/python-api.rst b/docs/python-api.rst
index 8dead7d..7f65a85 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -383,6 +383,17 @@ You can leave off the third item in the tuple to have the referenced column auto
     ], foreign_keys=[
         ("author_id", "authors")
     ])
+    
+Compound foreign keys can be created by passing in tuples of columns rather than strings:
+
+.. code-block:: python
+
+    foreign_keys=[
+        (("author_id", "person_id"), "authors", ("id", "person_id"))
+    ]
+
+This means that the ``author_id`` and ``person_id`` columns should be a compound foreign key that references the ``id`` and ``person_id`` columns in the ``authors`` table.
+
 
 .. _python_api_table_configuration:
 
@@ -867,6 +878,20 @@ The ``table.add_foreign_key(column, other_table, other_column)`` method takes th
 
 This method first checks that the specified foreign key references tables and columns that exist and does not clash with an existing foreign key. It will raise a ``sqlite_utils.db.AlterError`` exception if these checks fail.
 
+You can add compound foreign keys by passing a tuple of column names. For example:
+
+.. code-block:: python
+
+    db["authors"].insert_all([
+        {"id": 1, "person_id": 1, "name": "Sally"},
+        {"id": 2, "person_id": 2, "name": "Asheesh"}
+    ], pk="id")
+    db["books"].insert_all([
+        {"title": "Hedgehogs of the world", "author_id": 1, "person_id": 1},
+        {"title": "How to train your wolf", "author_id": 2, "person_id": 2},
+    ])
+    db["books"].add_foreign_key(("author_id", "person_id"), "authors", ("id", "person_id"))
+
 To ignore the case where the key already exists, use ``ignore=True``:
 
 .. code-block:: python