prepare_connection plugin hook

Closes:
- #574

Refs #567

---------

Co-authored-by: Simon Willison <swillison@gmail.com>

docs/plugins.rst

@@ -86,7 +86,7 @@ See the `LLM plugin documentation <https://llm.datasette.io/en/stable/plugins/tu
 Plugin hooks
 ------------
 
-Plugin hooks allow ``sqlite-utils`` to be customized. There is currently one hook.
+Plugin hooks allow ``sqlite-utils`` to be customized.
 
 .. _plugins_hooks_register_commands:
 
@@ -109,3 +109,29 @@ Example implementation:
             "Say hello world"
             click.echo("Hello world!")
 
+.. _plugins_hooks_prepare_connection:
+
+prepare_connection(conn)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This hook is called when a new SQLite database connection is created. You can
+use it to `register custom SQL functions <https://docs.python.org/2/library/sqlite3.html#sqlite3.Connection.create_function>`_,
+aggregates and collations. For example:
+
+.. code-block:: python
+
+    import click
+    import sqlite_utils
+
+    @sqlite_utils.hookimpl
+    def prepare_connection(conn):
+        conn.create_function(
+          "hello", 1, lambda name: f"Hello, {name}!"
+        )
+
+This registers a SQL function called ``hello`` which takes a single
+argument and can be called like this:
+
+.. code-block:: sql
+
+    select hello("world"); -- "Hello, world!"