QBCore Frameworkqbcore.netCommunity docs
On this page

Independent community guide · Verified 2026-09-21 · Updated 2026-09-21 · 4 min read

Database Documentation

QBCore installations commonly use MySQL or MariaDB through oxmysql. The important distinction is which resource owns each table. Installing the core schema does not install every optional resource's schema, and two inventory implementations need not store their data in the same place.

Database Overview

Core Database Components

The referenced qb-core/qbcore.sql creates players, bans and player_contacts. Other resources add their own tables. Keep the resource repository, deployed commit, schema file and local migrations together in your deployment inventory.

These examples are source-reviewed, not database migrations to apply blindly. Back up and test recovery before changing a populated database.

Database Structure

Core Framework Tables

Table or columnOwner in the referenced sourcesPurpose
playersqb-core/qbcore.sqlCharacter records, including JSON-encoded money, job and metadata fields
players.inventoryCore declares the column; qb-inventory loads/saves itPersisted player inventory for the referenced qb-inventory implementation
bansqb-core/qbcore.sqlBan records; treat identifiers and addresses as sensitive
player_contactsqb-core/qbcore.sqlContact records; not a guarantee of any third-party phone's schema

Resource-Specific Tables

TableSource ownerDo not confuse it with
playerskinsqb-clothing/qb-clothing.sqlPlayer inventory; this stores appearance data
player_vehiclesqb-vehicleshop/vehshop.sql, with integrations depending on itA list of every currently spawned vehicle
inventoriesqb-inventory/qb-inventory.sqlplayers.inventory; this is identifier-keyed non-player storage

Housing, banking, phones and custom businesses must be checked against their own SQL. A prefix such as phone_* is not a portable schema definition. See clothing, vehicle shop and inventory.

Quick Start

Essential Queries

Before inspecting data, confirm the selected database:

SELECT DATABASE();
SHOW TABLES LIKE 'players';
SHOW COLUMNS FROM players;

Use parameterized queries in a server-side resource. The ? placeholders below are supplied by oxmysql, not pasted unbound into a SQL GUI. The resource manifest must load @oxmysql/lib/MySQL.lua before this code; see the oxmysql setup example.

-- server.lua: a read-only helper, not a network event
local function readSavedInventory(citizenid)
    if type(citizenid) ~= 'string' or citizenid == '' then return nil end
    local row = MySQL.single.await(
        'SELECT inventory FROM players WHERE citizenid = ? LIMIT 1',
        { citizenid }
    )
    if not row then return nil end
    return row.inventory
end

This returns the persisted JSON string, not the live in-memory item table. A missing row returns nil. Access live inventory through the resource's server APIs; do not overwrite players.inventory while a player is online, because a subsequent save can overwrite your edit. Decode JSON only after checking the result and handle malformed values explicitly.

For appearance rather than inventory, the referenced clothing schema supports:

local appearance = MySQL.single.await(
    'SELECT model, skin FROM playerskins WHERE citizenid = ? AND active = ? LIMIT 1',
    { citizenid, 1 }
)

Here citizenid must come from a trusted server-side character lookup, and your application must authorize access. These helpers intentionally expose no client-callable endpoint and do not print personal data.

Performance Tips

Measure the expensive query before adding indexes. Use EXPLAIN on a representative read-only query, bound result sizes and compare the index definitions already present in SHOW CREATE TABLE. The core schema already indexes several identifiers; adding duplicate indexes is not an optimization.

Schema Documentation

Available Documentation

Best Practices

Data Integrity

Compare the deployed schema with the target resource SQL on staging. CREATE TABLE IF NOT EXISTS only handles absence; it does not upgrade column types or constraints in an existing table. Review migrate.sql separately from a fresh-install schema. Record completed migrations so an import is not accidentally repeated.

For a failed inventory or character migration, retain the original backup and inspect one minimized test record. Do not delete all records to make the error disappear. A rollback may require a matching database snapshot as well as the old code; decide that before deployment.

Performance

Avoid broad reads of player records in hot loops. Read only required fields, use the existing inventory/player APIs for live state and investigate query frequency as well as query duration. Batch work only when its error handling and consistency requirements are understood.

Security

Keep credentials in server-only configuration. Use a dedicated database account scoped to the required database, parameterized values and application-level authorization. Minimize player data in staging and support reports. Do not publish a connection string, a raw player table or database credentials in client scripts.

Sources

Checked 2026-09-21. These commits identify the documentation baseline, not a claim that all possible combinations have been runtime-tested.

Found an issue in this guide?

Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website