storage_t::sync_schema

std::map<std::string, sync_schema_result> sync_schema(bool preserve = false);

Compares database schema provided in storage with actual schema in database and performs automigration if something isn't equal.

Return value

Results of syncing a schema. Keys of map are equal table names and values are equal sync_schema_result enum value defined in ::sqlite_orm namespace.

enum class sync_schema_result {
    /**
     *  created new table, table with the same tablename did not exist
     */
    new_table_created,
    
    /**
     *  table schema is the same as storage, nothing to be done
     */
    already_in_sync,
        
    /**
     *  removed excess columns in table (than storage) without dropping a table
     */
    old_columns_removed,
        
    /**
     *  lacking columns in table (than storage) added without dropping a table
     */
    new_columns_added,
        
    /**
     *  both old_columns_removed and new_columns_added
     */
    new_columns_added_and_old_columns_removed,
       
    /**
     *  old table is dropped and new is recreated. Reasons :
     *      1. delete excess columns in the table than storage if preseve = false 
     *      2. Lacking columns in the table cannot be added due to NULL and DEFAULT constraint 
     *      3. Reasons 1 and 2 both together
     *      4. data_type mismatch between table and storage.
     */
    dropped_and_recreated,
};

Description

sync_schema call can eliminate all your data stored in database that's why you must know how it works if you care about your data. If you want to know what will happen to your tables after sync_schema call you can call sync_schema_simulate function and check returned value. sync_schema_simulate returns same result that sync_schema does but doesn't alter any table in fact.

If there are excess tables exist in db they are ignored (not dropped). sync_schema iterates all tables specified in storage (not in actual database) and compares storage object's schema provided by make_table function with actual schema in database.

• if table doesn't exist it is being created
• if table exists its colums are being compared with table_info from db and
  • if there are columns in db that do not exist in storage (excess) table will be dropped and recreated
  • if there are columns in storage that do not exist in db they will be added using `ALTER TABLE ... ADD COLUMN ...' command
  • if there is any column existing in both db and storage but differs by any of properties/constraints (type, pk, notnull, dflt_value) table will be dropped and recreated.

Be aware that sync_schema doesn't guarantee that data will not be dropped. It guarantees only that it will make db schema the same as you specified in make_storage function call. A good point is that if you have no db file at all it will be created and all tables also will be created with exact tables and columns you specified in make_storage, make_table and make_column call. The best practice is to call this function right after storage creation.

Parameters

(1) preserve affects on function behaviour in case it is needed to remove a column. If it is false so table will be dropped if there is column to remove, if true - table is being copied into another table, dropped and copied table is renamed with source table name. Warning: sync_schema doesn't check foreign keys cause it is unable to do so in sqlite3. If you know how to get foreign key info please submit an issue https://github.com/fnc12/sqlite_orm/issues . In other words preserve = false guarantees that sync_schema call has O(1) work time but preserve = true - O(n) where n is a number of rows to be copied during removing a column from table. Notice that column removal and rows copy is performed only once per storage's schema change. If schemas are equal sync_schema will alter nothing.