Added schema migration

Author: snej

include/sqnice/database.hh

@@ -256,6 +256,49 @@ namespace sqnice {
         /// @warning NEVER pass an untrusted string; it can enable SQL injection attacks!
         status pragma(const char* name, std::string_view value);
 
+#pragma mark - SCHEMA MIGRATION:
+
+        /// Returns the database's "user version", an app-defined version number. Initially 0.
+        [[nodiscard]] int64_t user_version() const;
+        
+        /// Sets the database's "user version", an app-defined version number.
+        status set_user_version(int64_t);
+
+        /// Simple schema upgrades. If the database's user version is equal to `old_version`,
+        /// executes the SQL command in `sql_command` and then sets the version to `new_version`.
+        /// The SQL will presumably change the database's schema by adding tables or indexes,
+        /// altering tables, etc.
+        /// It's recommended that you wrap all your migrations in a single transaction.
+        status migrate_from(int64_t old_version,
+                            int64_t new_version,
+                            std::string_view sql_command);
+
+        /// Simple schema upgrades. If the database's user version is less than `new_version`,
+        /// executes the SQL command(s) in `sql_command` and then sets the user version to
+        /// `new_version`.
+        /// The SQL will presumably change the database's schema by adding tables or indexes,
+        /// altering tables, etc.
+        /// It's recommended that you wrap all your migrations in a single transaction.
+        status migrate_to(int64_t new_version,
+                          std::string_view sql_command);
+
+        /// Simple schema upgrades. If the database's user version is equal to `old_version`,
+        /// calls `fn` and on success sets the user version to `new_version`.
+        /// The function will presumably change the database's schema by adding tables or indexes,
+        /// altering tables, etc.
+        /// It's recommended that you wrap all your migrations in a single transaction.
+        status migrate_from(int64_t old_version,
+                            int64_t new_version,
+                            std::function<status(database&)> fn);
+
+        /// Simple schema upgrades. If the database's user version is less than `new_version`,
+        /// calls `fn` and on success sets the user version to `new_version`.
+        /// The function will presumably change the database's schema by adding tables or indexes,
+        /// altering tables, etc.
+        /// It's recommended that you wrap all your migrations in a single transaction.
+        status migrate_to(int64_t new_version,
+                          std::function<status(database&)> fn);
+
 #pragma mark - STATUS:
 
         /// The status of the last operation on this database or its queries/commands/blob_handles.

src/database.cc

@@ -312,6 +312,42 @@ namespace sqnice {
     }
 
 
+    int64_t database::user_version() const {
+        return const_cast<database*>(this)->pragma("user_version");
+    }
+
+    status database::set_user_version(int64_t v) {
+        return pragma("user_version", v);
+    }
+
+    status database::migrate_from(int64_t old, int64_t nuu, function<status (database &)> fn) {
+        assert(old < nuu);
+        if (user_version() == old) {
+            if (auto rc = fn(*this); !ok(rc))
+                return rc;
+            set_user_version(nuu);
+        }
+        return status::ok;
+    }
+
+    status database::migrate_to(int64_t nuu, function<status (database &)> fn) {
+        if (user_version() < nuu) {
+            if (auto rc = fn(*this); !ok(rc))
+                return rc;
+            set_user_version(nuu);
+        }
+        return status::ok;
+    }
+
+    status database::migrate_from(int64_t old, int64_t nuu, string_view sql) {
+        return migrate_from(old, nuu, [sql](database& db) {return db.execute(sql);});
+    }
+
+    status database::migrate_to(int64_t nuu, string_view sql) {
+        return migrate_to(nuu, [sql](database& db) {return db.execute(sql);});
+    }
+
+
     int64_t database::pragma(const char* pragma) {
         return sqnice::query(*this, string("PRAGMA \"") + pragma + "\"").single_value_or<int>(0);
     }

test/testdb.cc

@@ -151,8 +151,8 @@ TEST_CASE_METHOD(sqnice_test, "SQNice callbacks", "[sqnice]") {
 }
 
 TEST_CASE("SQNice pool", "[sqnice]") {
-    sqnice::pool p("sqnice_test.sqlite3",
-                   sqnice::open_flags::delete_first | sqnice::open_flags::readwrite);
+    static constexpr string_view kDBPath = "sqnice_test.sqlite3";
+    sqnice::pool p(kDBPath, sqnice::open_flags::delete_first | sqnice::open_flags::readwrite);
     {
         auto db = p.borrow_writeable();
         CHECK(p.borrowed_count() == 1);
@@ -198,4 +198,63 @@ TEST_CASE("SQNice pool", "[sqnice]") {
         CHECK(p.try_borrow_writeable() == nullptr);
     }
     CHECK(p.borrowed_count() == 4);
+    sqnice::database::delete_file(kDBPath);
+}
+
+
+TEST_CASE("SQNice schema migration", "[sqnice]") {
+    static constexpr string_view kDBPath = "sqnice_test.sqlite3";
+    sqnice::database::delete_file(kDBPath);
+    auto open_v1 = [] {
+        sqnice::database db(kDBPath);
+        db.setup();
+        sqnice::transaction txn(db);
+        db.migrate_from(0, 1, R"""(
+            CREATE TABLE contacts (
+              id INTEGER PRIMARY KEY,
+              name TEXT NOT NULL,
+              phone TEXT NOT NULL,
+              address TEXT,
+              UNIQUE(name, phone)
+            );
+          )""");
+        txn.commit();
+        CHECK(db.user_version() == 1);
+    };
+
+    open_v1();
+
+    open_v1();
+
+    auto open_v2 = [] (int64_t expectedVersion) {
+        sqnice::database db(kDBPath);
+        sqnice::transaction txn(db);
+        CHECK(db.user_version() == expectedVersion);
+
+        // Migration for a newly created database, leaving it at version 2:
+        db.migrate_from(0, 2, R"""(
+            CREATE TABLE contacts (
+              id INTEGER PRIMARY KEY,
+              name TEXT NOT NULL,
+              phone TEXT NOT NULL,
+              address TEXT,
+              age INTEGER,
+              UNIQUE(name, phone)
+            );
+          )""");
+
+        // Migration to upgrade version 1 (above) to version 2:
+        db.migrate_to(2, "ALTER TABLE contacts ADD COLUMN age INTEGER");
+        txn.commit();
+
+        CHECK(db.user_version() == 2);
+
+        db.execute("INSERT INTO contacts (name, phone, age) VALUES ('Alice', '555-1919', 39)");
+    };
+
+    open_v2(1);
+
+    sqnice::database::delete_file(kDBPath);
+
+    open_v2(0);
 }