Database

The Database module provides a server-side SQLite database interface for persistent data storage. Use it to store player data, inventories, leaderboards, and any other persistent state. It provides both synchronous and asynchronous methods for executing queries and retrieving results.

Authority: Server -- Database operations can only be performed on the server.

---

Methods

Method	Parameters	Return Type	Authority	Description
Database.Initialize	path: string	void	Server	Sets the file path for the SQLite database. Only needs to be called once.
Database.Execute	query: string, params: table	boolean	Server	Runs a SQL command (CREATE TABLE, INSERT, UPDATE, DELETE). Returns true on success.
Database.ExecuteAsync	query: string, params: table, callback: function	void	Server	Same as Execute, but runs in the background. The callback receives a boolean success value.
Database.Select	query: string, params: table	table	Server	Runs a SELECT query and returns a list of rows. Each row has a .Columns table with the column values.
Database.SelectAsync	query: string, params: table, callback: function	void	Server	Same as Select, but runs in the background. The callback receives the rows table.

---

Examples

Initializing the Database

Blueprint

// Database operations are handled via Lua scripting on the server.

Lua

-- Initialize the database path (call once at startup)
Database.Initialize('Saved/Database/lua.db')

-- Create a table
Database.Execute('CREATE TABLE IF NOT EXISTS PlayerData (PlayerID TEXT PRIMARY KEY, PlayerName TEXT, Score INTEGER)')

JavaScript

// Database operations follow the same pattern via PuerTS or Helix JS bindings.
// Refer to the Lua examples for function signatures.

CRUD Operations

Blueprint

// CRUD operations are handled via Lua scripting on the server.

Lua

-- Insert a player record
Database.Execute(
    'INSERT OR REPLACE INTO PlayerData (PlayerID, PlayerName, Score) VALUES (?, ?, ?)',
    { 'p01', 'PlayerOne', 0 }
)

-- Select a player by ID
local results = Database.Select(
    'SELECT PlayerName, Score FROM PlayerData WHERE PlayerID = ?',
    { 'p01' }
)

for _, row in ipairs(results) do
    print(row.Columns.PlayerName, row.Columns.Score)
end

-- Update a player's score
Database.Execute(
    'UPDATE PlayerData SET Score = Score + 100 WHERE PlayerID = ?',
    { 'p01' }
)

-- Delete a player record (async)
Database.ExecuteAsync(
    'DELETE FROM PlayerData WHERE PlayerID = ?',
    { 'p01' },
    function(success)
        print("Deleted:", success)
    end
)

JavaScript

// Database CRUD operations follow the same SQL pattern.
// Refer to the Lua examples for function signatures.

Async Select

Blueprint

// Async database queries are handled via Lua scripting.

Lua

-- Async query that does not block the game thread
Database.SelectAsync('SELECT * FROM PlayerData', {}, function(rows)
    for _, row in ipairs(rows) do
        print("Player:", row.Columns.PlayerName)
    end
end)

JavaScript

// Async queries follow the same pattern via PuerTS bindings.
// Refer to the Lua examples for function signatures.

---

warning

Never store database credentials in source code. Use the server configuration file to manage connection secrets.