Enfusion Database Framework

Info This mod is permitted to be used for Make Arma Not War 2025 submissions and commercial use on monetized servers

Warning This framework is still in BETA. Until version 1.0.0 there is no backward compatibility guarantee! Expect some bugs/performance issues and function signature updates until then. Feedback via issue or discussion is welcome.

A database framework to connect the Enfusion engine with SQL-, document- and local file databases.

Note Are you trying to persist the entire world state and not just a few self scripted db entites? Consider using EnfusionPersistenceFramework which is built on top of this project.

🚀 Features

• ✅ Easy to setup your DB entities with the provided base classes
• ✅ Built-in GUID generation for DB entities to avoid expensive roundtrips to the database
• ✅ Powerful query builder to find DB entities by complex conditions
• ✅ Sync (blocking) and Async (non-blocking) APIs for adding/updating, finding, and removing DB entities
• ✅ Pagination and result sorting by nested properties
• ✅ Optional repository pattern for easy strong typed results and re-useable queries.
• 🚧 Migrations between storage backends e.g. JsonFile <-> Http:MySQL

Drivers

• ✅ InMemory for unit testing purposes
• ✅ JsonFile local .json files for workbench development and small data volumes
• ✅ BinaryFile local .bin files, same purpose as JSON but much smaller in filesize.
• 🚧 BIBackend local/cloud synced .bin files stored in the Bohemia Interactive session backend.
• 🚧 Http a web API proxy to other external storage services such as SQL and document databases.
  • ✅ Document Databases MongoDB
  • 🚧 SQL Databases SQLite, MySQL, PostgreSQL

📖 Documentation

Detailed information on the individual classes and best practices can be found here.

⚡ Quick start

[EDF_DbName.Automatic()]
class TAG_MyPersistentInfo : EDF_DbEntity
{
    float m_fNumber;
    string m_sText;

    //------------------------------------------------------------------------------------------------
    //! Db entities can not have a constructor with parameters, this is a limitation of the engine.
    //! Consult the docs for more info on this.
    static TAG_MyPersistentInfo Create(float number, string text)
    {
        TAG_MyPersistentInfo instance();
        instance.m_fNumber = number;
        instance.m_sText = text;
        return instance;
    }
};

class EDF_QuickstartAction : ScriptedUserAction
{
    //------------------------------------------------------------------------------------------------
    override void PerformAction(IEntity pOwnerEntity, IEntity pUserEntity)
    {
        // Get the connection info as an attribute or parse it from CLI params etc.
        EDF_JsonFileDbConnectionInfo connectInfo();
        connectInfo.m_sDatabaseName = "MyJsonDatabase";

        // Get a db context instance and save it somewhere to re-use in e.g. a singleton
        EDF_DbContext dbContext = EDF_DbContext.Create(connectInfo);

        // For convenience interact with the DB context through a repository
        EDF_DbRepository<TAG_MyPersistentInfo> repository = EDF_DbEntityHelper<TAG_MyPersistentInfo>.GetRepository(dbContext);

        // Add some entries
        repository.AddOrUpdateAsync(TAG_MyPersistentInfo.Create(13.37, "Hello"));
        repository.AddOrUpdateAsync(TAG_MyPersistentInfo.Create(42.42, "World!"));

        // Now find hello
        EDF_DbFindCondition condition = EDF_DbFind.Field("m_sText").Contains("Hello");
        EDF_DbFindCallbackSingle<TAG_MyPersistentInfo> helloHandler(this, "FindHelloHandler");
        repository.FindFirstAsync(condition, callback: helloHandler);
    }

    protected void FindHelloHandler(EDF_EDbOperationStatusCode statusCode, TAG_MyPersistentInfo result)
    {
        PrintFormat("FindHelloHandler invoked! - StatusCode: %1",
            typename.EnumToString(EDF_EDbOperationStatusCode, statusCode));

        if (result)
            PrintFormat("Result: %1(id: %2, number: %3, text: %4)",
                result, result.GetId(), result.m_fNumber, result.m_sText)
    }
};

You should see this in your script console after executing the user action

FindHelloHandler invoked! - StatusCode: SUCCESS
Result: TAG_MyPersistentInfo<0x0000020D41100670>(id: 646e0c40-0000-0000-32cd-65805811b000, number: 13.37, text: Hello)

And in your profile find these two files

• profile/.db/MyJsonDatabase/MyPersistentInfos/646e0c40-0000-0000-32cd-65805811b000.json
• profile/.db/MyJsonDatabase/MyPersistentInfos/646e0c40-0000-0001-1a8d-352051eea400.json

And inside 646e0c40-0000-0000-32cd-65805811b000.json

{
    "m_sId": "646e0c40-0000-0000-32cd-65805811b000",
    "m_fNumber": 13.36999,
    "m_sText": "Hello"
}