Database API

The Database component provides access to MongoDB for all persistent data storage. It uses a dual-database architecture with separate databases for authentication and game data.

Overview

Access the Database component via Database.Game (for game data) or Database.Auth (for authentication data).

Database.Game    -- Characters, vehicles, inventory, properties, phone data, etc.
Database.Auth    -- Accounts, bans

Server-Side Only: Database operations are only available on the server. Never attempt database queries from client-side code.

Params Table Pattern: All MongoDB methods use a single params table as the first argument — NOT separate positional arguments. See examples below.

Call Signature

Every database method follows the same pattern:

Database.Game:methodName({
    collection = "collectionName",
    query = { ... },        -- for find/update/delete
    document = { ... },     -- for insertOne
    documents = { ... },    -- for insert (bulk)
    update = { ... },       -- for update/updateOne
    options = { ... },      -- optional MongoDB options
    limit = 10,             -- optional result limit (find)
    aggregate = { ... },    -- pipeline stages (aggregate only)
}, function(success, result, insertedIds)
    -- success (boolean) - whether the operation succeeded
    -- result - data on success, error message string on failure
    -- insertedIds - array of IDs (insert operations only)
end)

Methods

findOne

Find a single document matching the query.

Database.Game:findOne({
    collection = "characters",
    query = { SID = 1 }
}, function(success, results)
    if success and results and #results > 0 then
        local character = results[1]
        print("Found:", character.First, character.Last)
    end
end)

findOne internally calls find with limit = 1. The callback receives an array — access the first element with results[1].

With projection (return only specific fields):

Database.Game:findOne({
    collection = "characters",
    query = { SID = 1 },
    options = {
        projection = { First = 1, Last = 1, Cash = 1 }
    }
}, function(success, results)
    if success and results and #results > 0 then
        -- results[1] only contains First, Last, Cash, _id
    end
end)

find

Find multiple documents matching the query.

Database.Game:find({
    collection = "characters",
    query = { ["Jobs.Id"] = "police" }
}, function(success, results)
    if success then
        print("Found", #results, "police officers")
    end
end)

With limit:

Database.Game:find({
    collection = "characters",
    query = {},
    limit = 10
}, function(success, results)
    if success then
        for _, char in ipairs(results) do
            print(char.First, char.Last)
        end
    end
end)

With options (sort, projection):

Database.Game:find({
    collection = "characters",
    query = {},
    options = {
        sort = { createdAt = -1 },
        projection = { First = 1, Last = 1, _id = 0 }
    },
    limit = 20
}, function(success, results)
    -- 20 most recent characters, names only
end)

insertOne

Insert a single document.

Database.Game:insertOne({
    collection = "characters",
    document = {
        SID = 1,
        First = "John",
        Last = "Doe",
        DOB = "1990-01-15",
        Gender = "Male",
        createdAt = os.time()
    }
}, function(success, count, ids)
    if success then
        print("Inserted with ID:", ids[1])
    end
end)

insertOne wraps the document into a single-element array and calls insert internally. The callback signature is (success, insertedCount, arrayOfIds).

insert

Insert multiple documents at once (bulk insert).

Database.Game:insert({
    collection = "logs",
    documents = {
        { type = "join", player = "John", timestamp = os.time() },
        { type = "join", player = "Jane", timestamp = os.time() },
        { type = "join", player = "Bob", timestamp = os.time() }
    }
}, function(success, insertedCount, ids)
    if success then
        print("Inserted", insertedCount, "documents")
    end
end)

The method name is insert, NOT insertMany. The params.documents field must be an array of document tables.

updateOne

Update a single document matching the query.

Database.Game:updateOne({
    collection = "characters",
    query = { SID = 1 },
    update = {
        ["$set"] = {
            job = "police",
            grade = "officer"
        }
    }
}, function(success, modifiedCount)
    if success then
        print("Modified", modifiedCount, "documents")
    end
end)

Increment values:

Database.Game:updateOne({
    collection = "characters",
    query = { SID = 1 },
    update = {
        ["$inc"] = { cash = 500 }
    }
})

Push to array:

Database.Game:updateOne({
    collection = "characters",
    query = { SID = 1 },
    update = {
        ["$push"] = { licenses = "drivers_license" }
    }
})

Multiple operations at once:

Database.Game:updateOne({
    collection = "characters",
    query = { SID = 1 },
    update = {
        ["$set"] = { job = "police", lastUpdated = os.time() },
        ["$inc"] = { arrests = 1 }
    }
})

update

Update all documents matching the query (bulk update).

Database.Game:update({
    collection = "characters",
    query = { job = "police", onDuty = true },
    update = {
        ["$set"] = { onDuty = false }
    }
}, function(success, modifiedCount)
    if success then
        print("Clocked out", modifiedCount, "officers")
    end
end)

The method name is update, NOT updateMany. Without the internal isUpdateOne flag, update applies to ALL matching documents.

deleteOne

Delete a single document matching the query.

Database.Game:deleteOne({
    collection = "characters",
    query = { SID = 1 }
}, function(success, deletedCount)
    if success and deletedCount > 0 then
        print("Character deleted")
    end
end)

delete

Delete all documents matching the query (bulk delete).

local thirtyDaysAgo = os.time() - (30 * 24 * 60 * 60)

Database.Game:delete({
    collection = "logs",
    query = { timestamp = { ["$lt"] = thirtyDaysAgo } }
}, function(success, deletedCount)
    if success then
        print("Deleted", deletedCount, "old logs")
    end
end)

The method name is delete, NOT deleteMany. Without the internal isDeleteOne flag, delete removes ALL matching documents.

findOneAndUpdate

Atomically find a document, update it, and return the result.

Database.Game:findOneAndUpdate({
    collection = "sequences",
    query = { _id = "characterSID" },
    update = {
        ["$inc"] = { value = 1 }
    },
    options = {
        returnDocument = "after"  -- return the updated document
    }
}, function(success, document)
    if success and document then
        print("New sequence value:", document.value)
    end
end)

This method is useful for atomic operations like generating sequential IDs.

count

Count documents matching the query.

Database.Game:count({
    collection = "characters",
    query = { job = "police", onDuty = true }
}, function(success, count)
    if success then
        print("Online police:", count)
    end
end)

aggregate

Run an aggregation pipeline.

Database.Game:aggregate({
    collection = "characters",
    aggregate = {
        {
            ["$group"] = {
                _id = "$job",
                count = { ["$sum"] = 1 }
            }
        },
        {
            ["$sort"] = { count = -1 }
        }
    }
}, function(success, results)
    if success then
        for _, result in ipairs(results) do
            print(result._id, "has", result.count, "members")
        end
    end
end)

The pipeline stages go in params.aggregate (NOT a separate pipeline argument).

Auth Database

The Auth database has the same methods as Game. Use it for accounts and bans:

-- Find account
Database.Auth:findOne({
    collection = "accounts",
    query = { Identifier = identifier }
}, function(success, results)
    if success and results and #results > 0 then
        local account = results[1]
        print("Account:", account.AccountID)
    end
end)

-- Check for ban
Database.Auth:findOne({
    collection = "bans",
    query = { Identifier = identifier, active = true }
}, function(success, results)
    if success and results and #results > 0 then
        print("Player is banned:", results[1].reason)
    end
end)

Deprecated Methods

The top-level Database:method() calls (without .Game or .Auth) still work but print deprecation warnings. Always use Database.Game:method() or Database.Auth:method().

-- ❌ Deprecated (prints warning)
Database:findOne({ collection = "characters", query = { SID = 1 } }, callback)

-- ✅ Correct
Database.Game:findOne({ collection = "characters", query = { SID = 1 } }, callback)

MySQL (oxmysql)

MySQL is available via the oxmysql resource for the inventory system and compatibility. It is NOT accessed through the Database component — use oxmysql exports directly:

-- oxmysql exports (not part of Database component)
exports.oxmysql:execute("SELECT * FROM inventory WHERE id = ?", { itemId }, function(results)
    -- Process results
end)

exports.oxmysql:scalar("SELECT COUNT(*) FROM inventory", {}, function(count)
    print("Total items:", count)
end)

exports.oxmysql:insert("INSERT INTO inventory (name, item_id, slot) VALUES (?, ?, ?)", {
    name, itemId, slot
}, function(insertId)
    print("Inserted row:", insertId)
end)

See oxmysql documentation for full API reference.

Best Practices

Always Use Database.Game or Database.Auth

Never use the top-level deprecated methods:

-- ✅ Good
Database.Game:findOne({ collection = "characters", query = { SID = 1 } }, cb)
Database.Auth:findOne({ collection = "accounts", query = { id = 1 } }, cb)

-- ❌ Bad (deprecated, prints warning)
Database:findOne({ collection = "characters", query = { SID = 1 } }, cb)

Handle Errors in Callbacks

Database.Game:findOne({
    collection = "characters",
    query = { SID = id }
}, function(success, results)
    if not success then
        print("Database error:", results) -- results is error message on failure
        return
    end

    if not results or #results == 0 then
        print("Character not found")
        return
    end

    local character = results[1]
    -- Safe to use character
end)

Use Params Table Correctly

All methods take a single params table. The fields vary by method:

Method	Required Fields	Optional Fields
`find` / `findOne`	`collection`, `query`	`options`, `limit`
`insertOne`	`collection`, `document`	`options`
`insert`	`collection`, `documents`	`options`
`updateOne` / `update`	`collection`, `query`, `update`	`options`
`deleteOne` / `delete`	`collection`, `query`	`options`
`findOneAndUpdate`	`collection`, `query`, `update`	`options`
`count`	`collection`, `query`	`options`
`aggregate`	`collection`, `aggregate`	—

Index Your Collections

Create indexes for frequently queried fields:

// MongoDB shell
db.characters.createIndex({ SID: 1 }, { unique: true })
db.inventory.createIndex({ owner: 1 })
db.vehicles.createIndex({ owner: 1, plate: 1 })
db.logs.createIndex({ timestamp: -1 })

Next Steps

Base API

Core framework exports

Logger API

Logging component

Database Architecture

Understanding the database system

Database Setup

Configure databases

Mythic Components API

Characters

Inventory

Jobs

Vehicles

HUD & Status

Finance

Phone

Doors

Status

Chat

Admin

Overview

Call Signature

Methods

findOne

find

insertOne

insert

updateOne

update

deleteOne

delete

findOneAndUpdate

count

aggregate

Auth Database

Deprecated Methods

MySQL (oxmysql)

Best Practices

Next Steps

Base API

Logger API

Database Architecture

Database Setup

Mythic Components API

Characters

Inventory

Jobs

Vehicles

HUD & Status

Finance

Phone

Doors

Status

Chat

Admin

​Overview

​Call Signature

​Methods

​findOne

​find

​insertOne

​insert

​updateOne

​update

​deleteOne

​delete

​findOneAndUpdate

​count

​aggregate

​Auth Database

​Deprecated Methods

​MySQL (oxmysql)

​Best Practices

​Next Steps

Base API

Logger API

Database Architecture

Database Setup

Overview

Call Signature

Methods

findOne

find

insertOne

insert

updateOne

update

deleteOne

delete

findOneAndUpdate

count

aggregate

Auth Database

Deprecated Methods

MySQL (oxmysql)

Best Practices

Next Steps