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 column | Owner in the referenced sources | Purpose |
|---|---|---|
players | qb-core/qbcore.sql | Character records, including JSON-encoded money, job and metadata fields |
players.inventory | Core declares the column; qb-inventory loads/saves it | Persisted player inventory for the referenced qb-inventory implementation |
bans | qb-core/qbcore.sql | Ban records; treat identifiers and addresses as sensitive |
player_contacts | qb-core/qbcore.sql | Contact records; not a guarantee of any third-party phone's schema |
Resource-Specific Tables
| Table | Source owner | Do not confuse it with |
|---|---|---|
playerskins | qb-clothing/qb-clothing.sql | Player inventory; this stores appearance data |
player_vehicles | qb-vehicleshop/vehshop.sql, with integrations depending on it | A list of every currently spawned vehicle |
inventories | qb-inventory/qb-inventory.sql | players.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
endThis 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
- Core schema: core fields and relationships.
- oxmysql diagnostics: installation, connection and schema failures.
- Inventory update migration: player inventory versus stashes, trunks and gloveboxes.
- Backup and restore: prepare recovery before changes.
- Resource update workflow: compare code, configuration and SQL together.
- Server optimization: investigate runtime and database bottlenecks.
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.
Commands
Learn how to register QBCore server commands, configure ACE-backed permissions and refresh player chat suggestions, with command examples and API references.
QBCore Database Schema: players Table & Core Tables
Every core QBCore database table explained: players, player_vehicles, houses and properties - columns, relationships and safe query patterns.
