> For the complete documentation index, see [llms.txt](https://acestudios.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://acestudios.gitbook.io/docs/jobs-and-economy/p2p-vehicle-marketplace/database.md).

# Database

Database tables used by ace\_p2pmarketplace, and how installation and migration work.

The marketplace uses **oxmysql** and adds its own tables next to your framework's vehicle table.

## Installation

Import `sql/install.sql` once with your database tool (HeidiSQL, phpMyAdmin, etc.). Every statement uses `CREATE TABLE IF NOT EXISTS`, so it's safe to run again.

{% hint style="info" %}
**Prerequisite:** your framework's vehicle table must already exist: `owned_vehicles` (ESX) or `player_vehicles` (QBCore/Qbox).
{% endhint %}

## Automatic migration

On every start the resource verifies the schema. **Missing tables and columns are added automatically**, so updates don't need manual SQL.

If the check, installation, migration or self-test fails, the marketplace is **disabled**. Players see a *Marketplace Unavailable* screen, and the console explains why, for example a missing table or column, missing `CREATE`/`ALTER` permission, or a wrong vehicle-table column.

{% hint style="warning" %}
Your database user needs **CREATE** and **ALTER** permissions for automatic installation and migration.
{% endhint %}

## Tables

| Table                            | Purpose                                                                                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ace_marketplace_listings`       | Sale and rental listings: seller, plate, model, title, description, category, prices, rental unit, test drive flag, status (`active` / `sold` / `rented` / `removed`), views. |
| `ace_marketplace_listing_photos` | Photo URLs per listing, with primary flag and order.                                                                                                                          |
| `ace_marketplace_rentals`        | Active and past rentals: owner, renter, price paid, payment method, duration, expiry, status, original garage.                                                                |
| `ace_marketplace_transactions`   | Every sale, rental, rental extension, refund and payout, with fee amount.                                                                                                     |
| `ace_marketplace_earnings`       | Seller earnings, `available` or `claimed`, with partial-claim support (`split_from`).                                                                                         |
| `ace_marketplace_fee_ledger`     | Marketplace fee revenue claimable by `Config.MarketplaceOwner`.                                                                                                               |
| `ace_marketplace_testdrives`     | Test drive records.                                                                                                                                                           |
| `ace_marketplace_vehicle_locks`  | Per-plate state (`idle` / `listed` / `rented` / `pending`) that prevents double transactions.                                                                                 |
| `ace_marketplace_payments`       | Payment holds, refunds and payouts that survive disconnects and restarts (`hold` / `pending` / `paying` / `paid` / `settled`).                                                |
| `ace_marketplace_guard`          | Always empty. Used to abort a transaction when a state check fails.                                                                                                           |

## Payment recovery

Rows in `ace_marketplace_payments` let the marketplace finish or refund payments after problems:

* A charge that doesn't complete (error, disconnect, restart) is refunded, immediately or on the player's next login.
* Earnings and fee claims that can't be paid right away are paid on the player's next login.

{% hint style="danger" %}
**Rows stuck at status `paying`** mean the server stopped while paying someone. Check whether the player got the money, then set the row to `paid` (they got it) or `pending` (they didn't, so it's retried).
{% endhint %}

## Photo storage

| `Config.Photos.Storage` | Where photos go                                                     |
| ----------------------- | ------------------------------------------------------------------- |
| `resource`              | `web/uploads/` inside the resource. Keep this folder when updating. |
| `fivemanage`            | Fivemanage, using the `ace_marketplace_fivemanage_key` convar.      |

The photo URLs are saved in `ace_marketplace_listing_photos`.