issue_comments

Documentation:

• https://sqlite-utils.datasette.io/en/latest/python-api.html#explicitly-creating-a-table
• https://sqlite-utils.datasette.io/en/latest/cli.html#creating-tables

I could add a --transform option to sqlite-utils create-table too.

Also needs comprehensive tests and documentation.

Example of that prototype working: ```pycon

from sqlite_utils import Database db = Database(memory=True) db["dogs"].create({"id": int, "name": str}, pk="id")

Initial prototype: diff diff --git a/sqlite_utils/db.py b/sqlite_utils/db.py index 18a442a..03fd345 100644 --- a/sqlite_utils/db.py +++ b/sqlite_utils/db.py @@ -875,6 +875,7 @@ class Database: hash_id_columns: Optional[Iterable[str]] = None, extracts: Optional[Union[Dict[str, str], List[str]]] = None, if_not_exists: bool = False, + transform: bool = False, ) -> "Table": """ Create a table with the specified name and the specified ``{column_name: type}`` columns. @@ -892,7 +893,39 @@ class Database: :param hash_id_columns: List of columns to be used when calculating the hash ID for a row :param extracts: List or dictionary of columns to be extracted during inserts, see :ref:`python_api_extracts` :param if_not_exists: Use ``CREATE TABLE IF NOT EXISTS`` - """ + :param transform: If table already exists, transform it to fit the specified schema + """ + # Transform table to match the new definition if table already exists: + if transform and self[name].exists(): + # First add missing columns and columns to drop + existing_columns = self[name].columns_dict + missing_columns = dict( + (col_name, col_type) + for col_name, col_type in columns.items() + if col_name not in existing_columns + ) + columns_to_drop = [ + column for column in existing_columns if column not in columns + ] + if missing_columns: + for col_name, col_type in missing_columns.items(): + self[name].add_column(col_name, col_type) + # Do we need to reset the column order? + column_order = None + if list(existing_columns) != list(columns): + column_order = list(columns) + # Only run .transform() if there is something to do + # TODO: this misses changes like pk= without also column changes + if columns_to_drop or missing_columns or column_order: + self[name].transform( + types=columns, + drop=columns_to_drop, + column_order=column_order, + not_null=not_null, + defaults=defaults, + pk=pk, + ) + return cast(Table, self[name]) sql = self.create_table_sql( name=name, columns=columns, @@ -1477,6 +1510,7 @@ class Table(Queryable): hash_id_columns: Optional[Iterable[str]] = None, extracts: Optional[Union[Dict[str, str], List[str]]] = None, if_not_exists: bool = False, + transform: bool = False, ) -> "Table": """ Create a table with the specified columns. @@ -1508,6 +1542,7 @@ class Table(Queryable): hash_id_columns=hash_id_columns, extracts=extracts, if_not_exists=if_not_exists, + transform=transform, ) return self Needs more thought about how things like just a change to pk= should work.

... but that's what the table.transform(...) method does already!

So maybe this is actually a transform=True parameter to create() that triggers table.transform(...) if necessary.

Maybe there should be a separate table.alter(...) method that does the actual work here, with .create(..., alter=True) as syntactic sugar for triggering that if the table exists already.

Thinking about this more, I think alter=True is a good name for this option even if it does more than the same option on .insert().

Could call it ensure=True here if it works differently enough from alter=True that the behavior could be confusing.

Should passing alter=True also drop any columns that aren't included in the new table structure?

It could even spot column types that aren't correct and fix those.

Is that consistent with the expectations set by how alter=True works elsewhere?

I'm not crazy about having to pass both alter=True and if_not_exists=True - maybe alter should imply if_not_exists.

Jeff suggested db[table].(..., alter=True) for this.

python db["urls"].create( { "url": str, "crawled": bool, "body": str, "headers": dict, "status": int, "status_text": str, }, pk="url", defaults={"crawled": False}, if_not_exists=True, alter=True, )