✨ add --defer-foreign-keys option to defer foreign key constraints during data transfer to SQLite

Author: techouse

src/mysql_to_sqlite3/cli.py

@@ -93,6 +93,9 @@
     help="Prefix indices with their corresponding tables. "
     "This ensures that their names remain unique across the SQLite database.",
 )
+@click.option(
+    "-D", "--defer-foreign-keys", is_flag=True, help="Defer foreign key constraints until the end of the transfer."
+)
 @click.option("-X", "--without-foreign-keys", is_flag=True, help="Do not transfer foreign keys.")
 @click.option(
     "-Z",
@@ -164,6 +167,7 @@ def cli(
     limit_rows: int,
     collation: t.Optional[str],
     prefix_indices: bool,
+    defer_foreign_keys: bool,
     without_foreign_keys: bool,
     without_tables: bool,
     without_data: bool,
@@ -212,6 +216,11 @@ def cli(
             limit_rows=limit_rows,
             collation=collation,
             prefix_indices=prefix_indices,
+            defer_foreign_keys=(
+                defer_foreign_keys
+                if not without_foreign_keys and not (mysql_tables is not None and len(mysql_tables) > 0)
+                else False
+            ),
             without_foreign_keys=without_foreign_keys or (mysql_tables is not None and len(mysql_tables) > 0),
             without_tables=without_tables,
             without_data=without_data,

src/mysql_to_sqlite3/transporter.py

@@ -95,6 +95,16 @@ def __init__(self, **kwargs: tx.Unpack[MySQLtoSQLiteParams]) -> None:
         else:
             self._without_foreign_keys = bool(kwargs.get("without_foreign_keys", False))
 
+        if not self._without_foreign_keys and not bool(self._mysql_tables) and not bool(self._exclude_mysql_tables):
+            self._defer_foreign_keys = bool(kwargs.get("defer_foreign_keys", False))
+            if self._defer_foreign_keys and sqlite3.sqlite_version_info < (3, 6, 19):
+                self._logger.warning(
+                    "SQLite %s lacks DEFERRABLE support – ignoring --defer-fks.", sqlite3.sqlite_version
+                )
+                self._defer_foreign_keys = False
+        else:
+            self._defer_foreign_keys = False
+
         self._without_data = bool(kwargs.get("without_data", False))
         self._without_tables = bool(kwargs.get("without_tables", False))
 
@@ -557,10 +567,12 @@ def _build_create_table_sql(self, table_name: str) -> str:
             )
             for foreign_key in self._mysql_cur_dict.fetchall():
                 if foreign_key is not None:
+                    deferrable_clause = " DEFERRABLE INITIALLY DEFERRED" if self._defer_foreign_keys else ""
                     sql += (
                         ',\n\tFOREIGN KEY("{column}") REFERENCES "{ref_table}" ("{ref_column}") '
                         "ON UPDATE {on_update} "
-                        "ON DELETE {on_delete}".format(**foreign_key)  # type: ignore[str-bytes-safe]
+                        "ON DELETE {on_delete}"
+                        "{deferrable}".format(**foreign_key, deferrable=deferrable_clause)  # type: ignore[str-bytes-safe]
                     )
 
         sql += "\n);"
@@ -765,12 +777,15 @@ def transfer(self) -> None:
                     self._logger.warning(
                         "Foreign key constraint violations found (%d violation%s):",
                         len(fk_violations),
-                        "s" if len(fk_violations) != 1 else ""
+                        "s" if len(fk_violations) != 1 else "",
                     )
                     for violation in fk_violations:
                         self._logger.warning(
                             "  → Table '%s' (row %s) references missing key in '%s' (constraint #%s)",
-                            violation[0], violation[1], violation[2], violation[3]
+                            violation[0],
+                            violation[1],
+                            violation[2],
+                            violation[3],
                         )
                 else:
                     self._logger.info("All foreign key constraints are valid.")

src/mysql_to_sqlite3/types.py

@@ -35,6 +35,7 @@ class MySQLtoSQLiteParams(tx.TypedDict):
     vacuum: t.Optional[bool]
     without_tables: t.Optional[bool]
     without_data: t.Optional[bool]
+    defer_foreign_keys: t.Optional[bool]
     without_foreign_keys: t.Optional[bool]
 
 
@@ -71,4 +72,5 @@ class MySQLtoSQLiteAttributes:
     _sqlite_json1_extension_enabled: bool
     _vacuum: bool
     _without_data: bool
+    _defer_foreign_keys: bool
     _without_foreign_keys: bool