sqlite3persistence.hpp

//  SPDX-License-Identifier: GPL-3.0-or-later
//
//  Copyright (c) 2013-2023 plan44.ch / Lukas Zeller, Zurich, Switzerland
//
//  Author: Lukas Zeller <luz@plan44.ch>
//
//  This file is part of p44utils.
//
//  p44utils is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  p44utils is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with p44utils. If not, see <http://www.gnu.org/licenses/>.
//

#ifndef __p44utils__sqlite3persistence__
#define __p44utils__sqlite3persistence__

#include "p44utils_common.hpp"

#include "sqlite3pp/sqlite3pp.h"

using namespace std;

namespace p44 {


  #define SQLITE_PERSISTENCE_ERR_MIGRATION -99
  #define SQLITE_PERSISTENCE_ERR_SCHEMATOONEW -98

  /// SQLite3 error code based error
  class SQLite3Error : public Error
  {
  public:
    static const char *domain();
    virtual const char *getErrorDomain() const;
    SQLite3Error(int aSQLiteError, const char *aSQLiteMessage, const char *aContextMessage = NULL);
    static ErrorPtr err(int aSQLiteError, const char *aSQLiteMessage, const char *aContextMessage = NULL);
  };


  class SQLite3Persistence : public sqlite3pp::database
  {
    typedef sqlite3pp::database inherited;
    bool initialized;
  protected:
    /// Get DB Schema upgrade SQL statements
    /// @param aFromVersion current version (0=no database)
    /// @param aToVersion input: desired version, output: version that is generated by returned SQL
    /// @return SQL statements needed to get to aToVersion, empty string if no migration is possible
    virtual string dbSchemaUpgradeSQL(int aFromVersion, int &aToVersion);
  public:
    SQLite3Persistence();
    virtual ~SQLite3Persistence();

    /// get current SQLite3 error as a Error object
    ErrorPtr error(const char *aContextMessage = NULL);

    /// connects to DB, and performs initialisation/migration as needed to be compatible with the given version
    /// @param aDatabaseFileName the SQLite3 database file path
    /// @param aNeededSchemaVersion the schema version needed to use the DB
    /// @param aFactoryReset if set, DB will be erased and recreated
    /// @param aLowestValidSchemaVersion if set to non-zero, all DB versions before this one will be considered obsolete and will cause a factory reset
    /// @return ok or error
    ErrorPtr connectAndInitialize(const char *aDatabaseFileName, int aNeededSchemaVersion, int aLowestValidSchemaVersion, bool aFactoryReset);

    /// check if database is available (was initialized correctly)
    bool isAvailable();

    /// disconnect and finalize
    void finalizeAndDisconnect();
  };

}


#endif /* defined(__p44utils__sqlite3persistence__) */