UT_SQLORM.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_SQLORM.h
 *
 * COMMENTS:
 *
 *  UT_SqlOrm provides support for ORM (object-relational mapping) backed by
 *  your sql backend of choice (currently only sqlite3 is supported). ORM maps
 *  a C++ object (or event a python object) to a database table. There are many
 *  benefits to using the ORM system over hand rolling the sql.
 *      1. The developer can waste less time on sql and spend more time on the
 *      taks they are actually working on while the ORM system handles all of
 *      the sql work under the hood.
 *      2. Provides an easy way to cache sql statements for more performant code
 *      3. Better multi-thread support as this is all handled internally
 *      4. Easily handle foreign relationships without the developer having to
 *      do anything past specifying the relationships between models.
 *
 *  An important feature of the ORM system is its migration abilities. The ORM
 *  system handles the migration of the different models internally when
 *  `orm.migrate` is called (it can be called multiple times pior to first use).
 *  The migration is a critical step to the ORM system and great care must be
 *  taken when defining the migrations.
 *      - Whenever a column is added or dropped a new migration must be made.
 *      NOTE: It cannot be made combined with an existing migration as it would
 *      cause your new migration to not run.
 *      - Each model must define its own migration to ensure each model migrates
 *      independently of each other.
 *      - Once a migration has been committed it CANNOT be changed as this would
 *      cause undefined behaviour to the database. If a change needs to be made
 *      just add a new migration step for that model.
 *
 *  For performing custom searches checkout UT_ORMQuerySet for building
 *  custom queries besides what are found from UT_ORMModelMeta.
 *
 *  Basic Usage:
 *  class User : public UT_ORMModel<User>
 *  {
 *      UT_DECLARE_MODEL();
 *
 *  public:
 *      class Meta : public UT_ORMModelMeta
 *      {
 *      public:
 *          Meta() : UT_ORModelMeta("user")
 *          {}
 *          void doBuild() override
 *          {
 *              // These can change at any time. If a change is made there MUST
 *              // a corresponding migration entry.
 *              addField("username", &User::myUsername, UT_ORMColumn::PrimaryKey);
 *              addField("password", &User::myPassword);
 *              addField("email", &User::myEmail);
 *          }
 *          void doMigrate(UT_ORMMigrationBuilder& builder) const override
 *          {
 *              static UT_StringLit theMigName = "user_mig";
 *              // 001 initial
 *              {
 *                  UT_ORMMigration& migration = builder.addMigration(theMigName.asHolder(), "user_001_initial");
 *
 *                  UT_ORMCreateTableOperation& create_table = migration.createModel("user");
 *                  create_table.addField("username", UT_ORMColumn::Type::String, UT_ORMColumn::PrimaryKey);
 *                  create_table.addField("password", UT_ORMColumn::Type::String);
 *              }
 *              // 002 add email field
 *              {
 *                  UT_ORMMigration& migration = builder.addMigration(theMigName.asHolder(), "user_002_add_email");
 *
 *                  UT_ORMColumn email_field("email", UT_ORMColumn::Type::String);
 *                  migration.addField(modelName(), std::move(email_field));
 *              }
 *          }
 *      };
 *
 *  private:
 *      UT_StringHolder myUsername;
 *      UT_StringHolder myPassword;
 *      UT_StringHolder myEmail;
 *  };
 *  // Define in the source file!!!
 *  UT_DEFINE_MODEL(User);  
 *
 *  int main()
 *  {
 *      UT_SqlOrm orm;
 *      // Make sure to register the model so that the ORM system knows about
 *      // its type
 *      orm.registerModelMeta<User>();
 *
 *      // Run the migration where all the different model meta will run their
 *      // specific migration steps (create tables, add/drop columns, etc).
 *
 *      // This create a new table called `user` with columns `username`,
 *      // `password`, and `email`.
 *      UT_ORMMigrationResult result;
 *      orm.migrate(result);
 *      if (result.error())
 *          return 1;
 *
 *      User user;
 *      user.myUsername = "someuser";
 *      user.myPassword = "somepassword";
 *      user.myEmail = "user@email.com";
 *      // Based on whether this specific object has already been saved we will
 *      // first either try to update the object or insert it.
 *      UT_ErrorCode ec;
 *      user.save(ec);
 *      if (ec)
 *          return 1;
 *
 *      if (UT_Optional<User> opt_user = User::filter(
 *              {UT::orm::FilterArg("username", User::metaInfo().primaryKey(), &user)});
 *              opt_user)
 *          return opt_user.value() == user; 
 *
 *      return 1;
 *  }
 *
 */

#ifndef __UT_SQLORM_H__
#define __UT_SQLORM_H__

#include "UT_API.h"

#include "UT_Array.h"
#include "UT_ArrayStringSet.h"
#include "UT_Debug.h"
#include "UT_Function.h"
#include "UT_Lock.h"
#include "UT_NonCopyable.h"
#include "UT_ORMError.h"
#include "UT_ORMField.h"
#include "UT_ORMMigrationResult.h"
#include "UT_ORMModelMeta.h"
#include "UT_ORMQuerySet.h"
#include "UT_Optional.h"
#include "UT_Options.h"
#include "UT_SGuid.h"
#include "UT_SQL.h"
#include "UT_SharedPtr.h"
#include "UT_StringHolder.h"
#include "UT_ThreadSpecificValue.h"
#include "UT_UniquePtr.h"
#include "UT_WorkBuffer.h"

#include <functional>
#include <variant>
#include <utility>

class UT_SqlOrm;
class UT_IORMOperation;
class UT_IStream;
class UT_OStream;
class UT_ORMMigrationBuilder;
class UT_ORMMigration;

class UT_ORMBaseModel
{
public:
    bool isAdding_() const { return myOrmAdding; }

protected:
    friend class UT_ORMModelMeta;
    bool myOrmAdding = true;
};

template <typename T>
class UT_ORMModel : public UT_ORMBaseModel
{
    friend class UT_ORMModelMeta;
public:
    UT_ORMModel(const UT_ORMModelMeta& meta = T::metaInfo()) :
        myModelMeta(meta)
    {}
    virtual ~UT_ORMModel() = default;
    UT_ORMModel(const UT_ORMModel&) = default;
    UT_ORMModel& operator=(const UT_ORMModel&) = default;

    bool save(
            UT_ErrorCode& ec,
            bool force_insert = false,
            bool force_update = false)
    {
        return myModelMeta.get().save(*this, ec, force_insert, force_update);
    }
    void remove(UT_ErrorCode& ec)
    {
        return myModelMeta.get().remove(*this, ec);
    }

    const UT_ORMModelMeta& meta() const { return myModelMeta.get(); }

    static UT_Array<T> fetch(
            const std::initializer_list<UT::orm::FilterArg>& args,
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template fetch<T>(args, ec);
    }

    template <typename PK>
    static UT_Optional<T> fetch(const PK& pk, UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template fetch<T>(pk, ec);
    }

    static UT_Array<T> fetchAll(
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template fetchAll<T>(ec);
    }

    static UT_Optional<T> filter(
            std::initializer_list<UT::orm::FilterArg>&& args,
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template filter<T>(
                std::forward<std::initializer_list<UT::orm::FilterArg>>(args),
                ec);
    }

#if 0
    template <typename C>
    static UT_ORMQuerySetResult findByForeignKey(
            const UT_StringRef& fk_name,
            const C& obj,
            UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template findByForeignKey<T, C>(fk_name, obj);
    }
#endif

    static std::pair<T, bool> getOrCreate(
            const std::initializer_list<UT::orm::FilterArg>& args,
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template getOrCreate<T>(args, ec);
    }

    static UT_Optional<T> create(
            const std::initializer_list<UT::orm::FilterArg>& args,
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template create<T>(args, ec);
    }

    template <typename ArrayT>
    static UT_Array<T> bulkFetch(const ArrayT& items, UT_ErrorCode& ec,
            const UT_StringRef& col_name = UT_StringHolder::theEmptyString,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template bulkFetch<T, ArrayT>(items, ec, col_name);
    }

    static void bulkSave(
            const UT_Array<T>& items,
            UT_ErrorCode& ec,
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template bulkSave<T>(items, ec);
    }

    template <typename... Args>
    static T fromDB(Args&&... args)
    {
        auto&& meta_info = T::metaInfo();
        return fromDB(meta_info, std::forward<Args>(args)...);
    }

    template <typename... Args>
    static T fromDB(const UT_ORMModelMeta& meta, Args&&... args)
    {
        return meta.template fromDB<T, Args...>(
                std::forward<Args>(args)...);
    }

    static bool exists(
            const std::initializer_list<UT::orm::FilterArg>& args,
            UT_ErrorCode& ec, 
            const UT_ORMModelMeta& meta = T::metaInfo())
    {
        return meta.template exists<T>(args, ec);
    }

protected:
    std::reference_wrapper<const UT_ORMModelMeta> myModelMeta;
};

class UT_API UT_SqlOrm
{
public:
    using error_callback_t
            = UT_Function<void(const UT_StringHolder&, const UT_ErrorCode&)>;

    explicit UT_SqlOrm(const UT_StringHolder& db_path);
    UT_SqlOrm();
    virtual ~UT_SqlOrm() = default;
    UT_NON_COPYABLE(UT_SqlOrm);

    void configure(
            const UT_StringHolder& db_path,
            error_callback_t&& clb = error_callback_t());

    UT_SqlStatement cursor() const
    {
        return UT_SqlStatement(database());
    }
    const UT_SqlDatabase& database() const
    {
        return SYSconst_cast(this)->getDatabase_();
    }
    UT_SqlDatabase& database()
    {
        return getDatabase_();
    }

    UT_AutoSqlTransaction transaction(
            UT_AutoSqlTransaction::commit_callback_t&& callback,
            bool savepoint = true)
    {
        return UT_AutoSqlTransaction(
                database(),
                std::forward<UT_AutoSqlTransaction::commit_callback_t>(
                        callback),
                savepoint);
    }

    void migrate(UT_ORMMigrationResult& result, bool collect_sql = false);

    void close(UT_ErrorCode* ec = nullptr);

    template <typename T>
    void registerModelMeta()
    {
        auto&& meta_info = T::metaInfo();
        for (auto&& m : myRegisteredMetas)
        {
            if (m->tableName() == meta_info.tableName())
                return;
        }

        // The pointer is a singleton so register it without the deleter since
        // the singleton will manage that part
        UT_SharedPtr<typename T::Meta> ptr(
                SYSconst_cast(&meta_info),
                UT::detail::no_op_delete<typename T::Meta>());

        ptr->resetInternals();
        myBuildStack.emplace_back(ptr);
        myRegisteredMetas.emplace_back(ptr);
    }

    UT_ORMModelMeta* registerModelMeta(
            const UT_SharedPtr<UT_ORMModelMeta>& meta)
    {
        for (auto&& m : myRegisteredMetas)
        {
            if (m->tableName() == meta->tableName())
                return m.get();
        }

        meta->resetInternals();
        myBuildStack.emplace_back(meta);
        myRegisteredMetas.emplace_back(meta);
        return meta.get();
    }

    UT_SharedPtr<UT_ORMModelMeta> lookupMeta(const UT_StringView& name)
    {
        for (auto&& m : myRegisteredMetas)
        {
            if (UT_StringView(m->tableName()) == name)
                return m;
        }
        return nullptr;
    }

    const UT_Array<UT_SharedPtr<UT_ORMModelMeta>>& metas() const
    {
        return myRegisteredMetas;
    }

protected:
    friend class UT_SqlOrmTable;

    static UT_UniquePtr<UT_IORMOperation> createOperation(
            const UT_StringRef& type);

    UT_SqlDatabase& getDatabase_();

    void error_(const UT_StringHolder& error, const UT_ErrorCode& ec);

    UT_Array<std::pair<UT_SharedPtr<UT_ORMMigration>, bool>> sortMigrations_(
            const UT_Array<UT_SharedPtr<UT_ORMMigration>>& migrations,
            const UT_StringSet& applied_migrations,
            UT_ErrorCode& ec);

    void recordMigration_(const UT_ORMMigration& mig);
    void collectAppliedMigrations_(
            UT_StringSet& applied_migrations,
            UT_StringHolder& message,
            UT_ErrorCode& ec);
    void createMigrationTableIfNotExist_(
            UT_StringHolder& message,
            UT_ErrorCode& ec);

    UT_Options myOptions;
    UT_ThreadSpecificValue<UT_SqlDatabase> myDB;
    error_callback_t myErrorCallback;

    UT_Lock myInternalLock;
    SYS_AtomicInt32 myHasConfiguredInternals;

    // Meta objects waiting to be built
    UT_Array<UT_SharedPtr<UT_ORMModelMeta>> myBuildStack;

    UT_Array<UT_SharedPtr<UT_ORMModelMeta>> myRegisteredMetas;
};

#define UT_DECLARE_MODEL()                                                     \
public:                                                                        \
    class Meta;                                                                \
    friend class UT_ORMModelMeta;                                              \
    static const Meta& metaInfo();

#define UT_DEFINE_MODEL(_model_)                                               \
    const _model_::Meta& _model_::metaInfo()                                   \
    {                                                                          \
        static Meta _instance;                                                 \
        return _instance;                                                      \
    }

#endif // __UT_SQLORM_H__