From fc38480e026d39ad7a9020e9e07336c639f1dbfd Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Sat, 27 Aug 2022 16:03:35 -0700 Subject: [PATCH] Docs for .create(transform=True), refs #467 --- docs/python-api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/python-api.rst b/docs/python-api.rst index c68611c..b8794f2 100644 --- a/docs/python-api.rst +++ b/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 ` 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