Database

HELIX provides a built-in database system through the Database module, backed by SQLite. This gives you persistent storage for player data, inventories, leaderboards, world state, and anything else that needs to survive a server restart.

Initializing the Database

The database file lives on your server and is created automatically when you first initialize. Call Database.Initialize once with the file path for your .db file.

Blueprint

Blueprint— Initialize a SQLite databaseScroll to zoom · Drag to pan · Drag nodes to move

Lua

-- Initialize (or create) a SQLite database
Database.Initialize("Saved/Database/my_world.db")

JavaScript

// Initialize (or create) a SQLite database
Database.Initialize("Saved/Database/my_world.db");

Creating Tables

Define your schema with standard SQL. Run this on server start so your tables are always ready.

Blueprint

Blueprint— Create a players table with SQLScroll to zoom · Drag to pan · Drag nodes to move

Lua

Database.Execute([[
    CREATE TABLE IF NOT EXISTS players (
        id TEXT PRIMARY KEY,
        name TEXT,
        money INTEGER DEFAULT 0,
        inventory TEXT DEFAULT '[]',
        last_position TEXT
    )
]])

JavaScript

Database.Execute(`
    CREATE TABLE IF NOT EXISTS players (
        id TEXT PRIMARY KEY,
        name TEXT,
        money INTEGER DEFAULT 0,
        inventory TEXT DEFAULT '[]',
        last_position TEXT
    )
`);

CRUD Operations

Use Database.Execute for writes and Database.Select for reads. Parameterized queries keep your data safe from injection.

Blueprint

Blueprint— CRUD operations: insert, update, select, deleteScroll to zoom · Drag to pan · Drag nodes to move

Lua

-- Insert a new player
Database.Execute("INSERT OR IGNORE INTO players (id, name) VALUES (?, ?)",
    {player:GetSteamID(), player:GetName()})

-- Update player money
Database.Execute("UPDATE players SET money = ? WHERE id = ?",
    {500, player:GetSteamID()})

-- Read player data
local rows = Database.Select("SELECT * FROM players WHERE id = ?",
    {player:GetSteamID()})
for _, row in ipairs(rows) do
    print(row.Columns.name, row.Columns.money)
end

-- Delete a player record
Database.Execute("DELETE FROM players WHERE id = ?", {player:GetSteamID()})

JavaScript

// Insert a new player
Database.Execute("INSERT OR IGNORE INTO players (id, name) VALUES (?, ?)",
    player.GetSteamID(), player.GetName());

// Update player money
Database.Execute("UPDATE players SET money = ? WHERE id = ?",
    500, player.GetSteamID());

// Read player data
const rows = Database.Select("SELECT * FROM players WHERE id = ?",
    player.GetSteamID());

// Delete a player record
Database.Execute("DELETE FROM players WHERE id = ?", player.GetSteamID());

Saving Player Data on Events

A common pattern is to save data when players disconnect and load it when they join.

Blueprint

Blueprint— Save player position on disconnectScroll to zoom · Drag to pan · Drag nodes to move

Blueprint— Load player position on joinScroll to zoom · Drag to pan · Drag nodes to move

Lua

-- Save position on disconnect
RegisterServerEvent("HEvent:PlayerUnloaded", function(controller)
    local char = controller:GetControlledCharacter()
    if char then
        local pos = char:K2_GetActorLocation()
        Database.Execute("UPDATE players SET last_position = ? WHERE id = ?",
            {tostring(pos), tostring(controller)})
    end
end)

-- Load position on join
RegisterServerEvent("HEvent:PlayerReady", function(controller)
    local rows = Database.Select("SELECT last_position FROM players WHERE id = ?",
        {tostring(controller)})
    if #rows > 0 and rows[1].Columns.last_position then
        -- Parse and teleport to saved position
    end
end)

JavaScript

// Using Helix server-side events for player lifecycle
Helix.server(() => {
    Helix.on("PlayerDisconnect", (player) => {
        // Save position on disconnect
        const pos = player.GetCharacter().K2_GetActorLocation();
        // Use your database ORM to persist
    });

    Helix.on("PlayerReady", (player) => {
        // Load position on join
        // Use your database ORM to query
    });
});

Async Operations

For operations that shouldn't block the game loop, use Database.ExecuteAsync and Database.SelectAsync. These run in the background and call a callback function when complete.

tip

Always use parameterized queries (? placeholders) instead of string concatenation. This prevents SQL injection and handles special characters automatically.