add_foreign_key can now detect table and pk, refs #25

docs/cli.rst

@@ -300,12 +300,16 @@ Adding foreign key constraints
 
 The ``add-foreign-key`` command can be used to add new foreign key references to an existing table - something which SQLite's ``ALTER TABLE`` command does not support.
 
-See :ref:`python_api_add_foreign_key` in the Python API documentation for further details and warnings (this could corrupt your database).
-
 To add a foreign key constraint pointing the ``books.author_id`` column to ``authors.id`` in another table, do this::
 
     $ sqlite-utils add-foreign-key books.db books author_id authors id
 
+If you omit the other table and other column references ``sqlite-utils`` will attempt to guess them - so the above example could instead look like this::
+
+    $ sqlite-utils add-foreign-key books.db books author_id
+
+See :ref:`python_api_add_foreign_key` in the Python API documentation for further details, including how the automatic table guessing mechanism works.
+
 .. _cli_create_index:
 
 Creating indexes

docs/python-api.rst

@@ -334,6 +334,11 @@ Here's an example of this mechanism in action:
     ])
     db["books"].add_foreign_key("author_id", "authors", "id")
 
+The ``table.add_foreign_key(column, other_table, other_column)`` method takes the name of the column, the table that is being referenced and the key column within that other table. If you ommit the ``other_column`` argument the primary key from that table will be used automatically. If you omit the ``other_table`` argument the table will be guessed based on some simple rules:
+
+- If the column is of format ``author_id``, look for tables called ``author`` or ``authors``
+- If the column does not end in ``_id``, try looking for a table with the exact name of the column or that name with an added ``s``
+
 .. _python_api_hash:
 
 Setting an ID based on the hash of the row contents