# 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](/docs/resources/qb-clothing), [vehicle shop](/docs/resources/qb-vehicleshop) and [inventory](/docs/resources/qb-inventory).

## Quick Start

### Essential Queries

Before inspecting data, confirm the selected database:

```sql
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](/docs/troubleshooting/oxmysql#verify-a-read-only-query).

```lua
-- 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:

```lua
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](/docs/database/core-schema): core fields and relationships.
- [oxmysql diagnostics](/docs/troubleshooting/oxmysql): installation, connection and schema failures.
- [Inventory update migration](/docs/troubleshooting/inventory-updates): player inventory versus stashes, trunks and gloveboxes.
- [Backup and restore](/docs/migration/tools/backup-restore): prepare recovery before changes.
- [Resource update workflow](/docs/migration/resource-updates): compare code, configuration and SQL together.
- [Server optimization](/docs/performance/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.

- [Core SQL, 9b3cddcc](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/qbcore.sql).
- [Inventory loading and saving, dc3d07fc](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/functions.lua).
- [Inventory SQL, dc3d07fc](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/qb-inventory.sql).
- [Clothing SQL, 8cca4009](https://github.com/qbcore-fivem/qb-clothing/blob/8cca4009dd473ab30c30e443ecad50830b816ed7/qb-clothing.sql).
- [Vehicle-shop SQL, e8652970](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/vehshop.sql).
