db[table].create(..., transform=True) and create-table --transform

Closes #467

docs/cli-reference.rst

@@ -865,6 +865,7 @@ See :ref:`cli_create_table`.
                                 foreign key
       --ignore                  If table already exists, do nothing
       --replace                 If table already exists, replace it
+      --transform               If table already exists, try to transform the schema
       --load-extension TEXT     Path to SQLite extension, with optional :entrypoint
       -h, --help                Show this message and exit.
 

docs/cli.rst

@@ -1520,6 +1520,8 @@ You can specify foreign key relationships between the tables you are creating us
 
 If a table with the same name already exists, you will get an error. You can choose to silently ignore this error with ``--ignore``, or you can replace the existing table with a new, empty table using ``--replace``.
 
+You can also pass ``--transform`` to transform the existing table to match the new schema. See :ref:`python_api_explicit_create` in the Python library documentation for details of how this option works.
+
 .. _cli_duplicate_table:
 
 Duplicating tables

docs/python-api.rst

@@ -554,6 +554,25 @@ To do nothing if the table already exists, add ``if_not_exists=True``:
         "name": str,
     }, pk="id", if_not_exists=True)
 
+You can also pass ``transform=True`` to have any existing tables :ref:`transformed <python_api_transform>` to match your new table specification. This is a **dangerous operation** as it may drop columns that are no longer listed in your call to ``.create()``, so be careful when running this.
+
+.. code-block:: python
+
+    db["cats"].create({
+        "id": int,
+        "name": str,
+        "weight": float,
+    }, pk="id", transform=True)
+
+The ``transform=True`` option will update the table schema if any of the following have changed:
+
+- The specified columns or their types
+- The specified primary key
+- The order of the columns, defined using ``column_order=``
+- The ``not_null=`` or ``defaults=`` arguments
+
+Changes to ``foreign_keys=`` are not currently detected and applied by ``transform=True``.
+
 .. _python_api_compound_primary_keys:
 
 Compound primary keys