Add -o/--column-order option to insert and upsert

docs/cli-reference.rst

@@ -311,6 +311,7 @@ See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`, :ref:`cli_insert_unstr
       --not-null TEXT           Columns that should be created as NOT NULL
       --default <TEXT TEXT>...  Default value that should be set for a column
       --type <TEXT CHOICE>...   Column types to use when creating the table
+      -o, --column-order TEXT   Columns that should come first in the created table
       --no-detect-types         Treat all CSV/TSV columns as TEXT
       --analyze                 Run ANALYZE at the end of this operation
       --load-extension TEXT     Path to SQLite extension, with optional :entrypoint
@@ -375,6 +376,7 @@ See :ref:`cli_upsert`.
       --not-null TEXT           Columns that should be created as NOT NULL
       --default <TEXT TEXT>...  Default value that should be set for a column
       --type <TEXT CHOICE>...   Column types to use when creating the table
+      -o, --column-order TEXT   Columns that should come first in the created table
       --no-detect-types         Treat all CSV/TSV columns as TEXT
       --analyze                 Run ANALYZE at the end of this operation
       --load-extension TEXT     Path to SQLite extension, with optional :entrypoint

docs/cli.rst

@@ -1423,6 +1423,19 @@ To import them as ``NULL`` values instead, use the ``--empty-null`` option:
 
     sqlite-utils insert creatures.db creatures creatures.csv --csv --empty-null
 
+.. _cli_insert_column_order:
+
+Setting the column order
+------------------------
+
+When ``insert`` or ``upsert`` creates a new table the columns are ordered based on the incoming data. Use ``-o`` (or ``--column-order``) one or more times to say which columns should come first:
+
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.csv --csv -o name -o age
+
+Any columns that are not listed keep their original order after the ones you specify. This only affects tables created by the command - the order of columns in an existing table is left unchanged.
+
 .. _cli_insert_csv_tsv_delimiter:
 
 Alternative delimiters and quote characters

sqlite_utils/cli.py

@@ -1032,6 +1032,13 @@ def inner(fn):
                     multiple=True,
                     help="Column types to use when creating the table",
                 ),
+                click.option(
+                    "-o",
+                    "--column-order",
+                    type=str,
+                    multiple=True,
+                    help="Columns that should come first in the created table",
+                ),
                 click.option(
                     "--no-detect-types",
                     is_flag=True,
@@ -1087,6 +1094,7 @@ def insert_upsert_implementation(
     not_null=None,
     default=None,
     types=None,
+    column_order=None,
     no_detect_types=False,
     analyze=False,
     load_extension=None,
@@ -1116,6 +1124,8 @@ def _insert_docs(docs, tracker=None):
             extra_kwargs["defaults"] = dict(default)
         if column_type_overrides:
             extra_kwargs["columns"] = column_type_overrides
+        if column_order:
+            extra_kwargs["column_order"] = list(column_order)
         if upsert:
             extra_kwargs["upsert"] = upsert
 
@@ -1385,6 +1395,7 @@ def insert(
     not_null,
     default,
     types,
+    column_order,
     strict,
 ):
     """
@@ -1479,6 +1490,7 @@ def rows():
             not_null=not_null,
             default=default,
             types=types,
+            column_order=column_order,
             strict=strict,
             code=code,
         )
@@ -1514,6 +1526,7 @@ def upsert(
     not_null,
     default,
     types,
+    column_order,
     no_detect_types,
     analyze,
     load_extension,
@@ -1565,6 +1578,7 @@ def upsert(
             not_null=not_null,
             default=default,
             types=types,
+            column_order=column_order,
             no_detect_types=no_detect_types,
             analyze=analyze,
             load_extension=load_extension,

tests/test_cli_insert.py

@@ -79,6 +79,27 @@ def test_insert_json_flatten_nl(tmpdir):
     ]
 
 
+@pytest.mark.parametrize("command", ("insert", "upsert"))
+@pytest.mark.parametrize(
+    "args,expected_columns",
+    (
+        ([], ["id", "name", "age"]),
+        (["-o", "name"], ["name", "id", "age"]),
+        (["--column-order", "age", "-o", "name"], ["age", "name", "id"]),
+    ),
+)
+def test_insert_column_order(db_path, tmpdir, command, args, expected_columns):
+    json_path = str(tmpdir / "dog.json")
+    with open(json_path, "w") as fp:
+        fp.write(json.dumps({"id": 1, "name": "Cleo", "age": 4}))
+    result = CliRunner().invoke(
+        cli.cli, [command, db_path, "dogs", json_path, "--pk", "id"] + args
+    )
+    assert result.exit_code == 0
+    columns = [c.name for c in Database(db_path).table("dogs").columns]
+    assert columns == expected_columns
+
+
 @pytest.mark.parametrize(
     "args,expected_pks",
     (