feat: add Database.merge() and sqlite-utils merge command

Implements the ability to merge tables from one or more source SQLite
databases into a destination database, as requested in #491.

Python API:
    db.merge([src1, src2], alter=True, replace=False, ignore=False, tables=None)
  - source_dbs can be Database objects or file paths
  - Tables not in dest are created; existing tables have rows inserted
  - alter=True adds missing columns to existing destination tables
  - replace=True overwrites rows with matching primary keys
  - ignore=True skips rows with conflicting primary keys
  - tables= limits which tables are merged
  - Virtual tables and their shadow tables are automatically skipped

CLI:
    sqlite-utils merge combined.db one.db two.db [options]
  - Supports --alter, --replace, --ignore, --pk, --table, --load-extension

Closes #491
This commit is contained in:
Abhishek Yadav 2026-03-22 20:49:01 +05:30
commit 37caace215
4 changed files with 418 additions and 0 deletions

View file

@ -1057,6 +1057,45 @@ That will look for SpatiaLite in a set of predictable locations. To load it from
sqlite-utils create-database empty.db --init-spatialite --load-extension /path/to/spatialite.so
.. _cli_merge:
Merging databases
=================
Use ``sqlite-utils merge`` to merge tables from one or more source databases into a destination database.
Tables that do not exist in the destination are created. Tables that already exist have their rows inserted.
.. code-block:: bash
sqlite-utils merge combined.db one.db two.db
To automatically add missing columns to existing destination tables, use ``--alter``:
.. code-block:: bash
sqlite-utils merge combined.db one.db two.db --alter
To replace rows that have conflicting primary keys, use ``--replace``:
.. code-block:: bash
sqlite-utils merge combined.db one.db two.db --replace
To skip rows that have conflicting primary keys, use ``--ignore``:
.. code-block:: bash
sqlite-utils merge combined.db one.db two.db --ignore
To merge only specific tables, use ``--table`` (can be specified multiple times):
.. code-block:: bash
sqlite-utils merge combined.db one.db two.db --table mytable
Virtual tables (such as FTS indexes) and their shadow tables are automatically skipped.
.. _cli_inserting_data:
Inserting JSON data