Docs for /db/-/create alter: true option, refs #2101

docs/json_api.rst

@@ -834,19 +834,22 @@ To create a table, make a ``POST`` to ``/<database>/-/create``. This requires th
 
 The JSON here describes the table that will be created:
 
-*   ``table`` is the name of the table to create. This field is required.
-*   ``columns`` is a list of columns to create. Each column is a dictionary with ``name`` and ``type`` keys.
+* ``table`` is the name of the table to create. This field is required.
+* ``columns`` is a list of columns to create. Each column is a dictionary with ``name`` and ``type`` keys.
 
-    -   ``name`` is the name of the column. This is required.
-    -   ``type`` is the type of the column. This is optional - if not provided, ``text`` will be assumed. The valid types are ``text``, ``integer``, ``float`` and ``blob``.
+  - ``name`` is the name of the column. This is required.
+  - ``type`` is the type of the column. This is optional - if not provided, ``text`` will be assumed. The valid types are ``text``, ``integer``, ``float`` and ``blob``.
 
-*   ``pk`` is the primary key for the table. This is optional - if not provided, Datasette will create a SQLite table with a hidden ``rowid`` column.
+* ``pk`` is the primary key for the table. This is optional - if not provided, Datasette will create a SQLite table with a hidden ``rowid`` column.
 
-    If the primary key is an integer column, it will be configured to automatically increment for each new record.
+  If the primary key is an integer column, it will be configured to automatically increment for each new record.
 
-    If you set this to ``id`` without including an ``id`` column in the list of ``columns``, Datasette will create an integer ID column for you.
+  If you set this to ``id`` without including an ``id`` column in the list of ``columns``, Datasette will create an auto-incrementing integer ID column for you.
 
-*   ``pks`` can be used instead of ``pk`` to create a compound primary key. It should be a JSON list of column names to use in that primary key.
+* ``pks`` can be used instead of ``pk`` to create a compound primary key. It should be a JSON list of column names to use in that primary key.
+* ``ignore`` can be set to ``true`` to ignore existing rows by primary key if the table already exists.
+* ``replace`` can be set to ``true`` to replace existing rows by primary key if the table already exists.
+* ``alter`` can be set to ``true`` if you want to  automatically add any missing columns to the table. This requires the :ref:`permissions_alter_table` permission.
 
 If the table is successfully created this will return a ``201`` status code and the following response:
 
@@ -925,6 +928,8 @@ You can avoid this error by passing the same ``"ignore": true`` or ``"replace":
 
 To use the ``"replace": true`` option you will also need the :ref:`permissions_update_row` permission.
 
+Pass ``"alter": true`` to automatically add any missing columns to the existing table that are present in the rows you are submitting. This requires the :ref:`permissions_alter_table` permission.
+
 .. _TableDropView:
 
 Dropping tables