Database and bridge

Supported reads#

The connection is on by default for every server and needs no server.cfg line. To stop it for one server, open the server under Servers and use “Disable connection” on the Tosun Connect card; the same card turns it back on. With set tosun_db_bridge_manual "1" in server.cfg, tosun_db_bridge_enabled and tosun_db_bridge_money_write are read from server.cfg as before, and each stays off unless set to "1". If the legacy full mirror is enabled on purpose (ts.panelMirror.enabled = true in configs/anticheat_config.lua), the bridge stays off so that mirror keeps working. QBCore/Qbox reads players and player_vehicles; ESX reads users and owned_vehicles; ban and detection reads use ts_anticheat and ac_detections. Supported operations are player lists, one character detail, that character’s vehicles, bans and anticheat logs. These six allowed tables do not cover every framework table; custom stashes, business, housing and banking tables are not automatically discovered.

Bounded on-demand reads#

When idle, the bridge polls the panel over HTTPS about every 10 seconds without querying the game database. List pages return at most 25 results; character detail returns one. Results are limited to 65,536 bytes and requested schema information is cached for five minutes. No data query runs if the required unique/owner index structure cannot be verified, including missing or unsuitable indexes or more than 64 index metadata rows. unsupported_index does not mean records do not exist; suitable composite indexes are supported for vehicle queries.

A response deadline does not cancel SQL#

The default SQL response wait is 5,000 ms. query_timeout ends the panel’s wait; the actual query may still be running. SQL capacity remains occupied until its first real callback, and another read returns query_busy. A late response does not change the previous view. If no callback arrives, the deadline does not automatically free capacity. The server administrator should inspect the connection and database; restarting the resource does not prove SQL cancellation. Only the server owner may optionally add the following set line to server.cfg. The value is clamped to 1,000–10,000 ms; an invalid or infinite number uses 5,000 ms. This setting does not speed up SQL or automatically retry queries.

set tosun_db_bridge_query_timeout_ms "5000"

Treat balance edits separately#

Online balance editing (setting an online character’s cash or bank total from the panel) is on by default. Panel users with the admin or owner role (economy permission) can use it. The character must be online and the expected current balance must match; otherwise stale_balance is returned and nothing changes. The panel shows a confirmation summary before sending, and every request is written to the audit log. The operation sets the total, it does not add to it, and it never falls back to offline SQL writes. unknown_outcome or a connection ambiguity is never retried automatically. Check the in-game balance and audit records before another write; do not delete uncertain-operation KVP records to force a repeat. To stop reads and balance edits for one server, use “Disable connection” on its Tosun Connect card. To keep reads but turn off balance edits, use manual mode: set tosun_db_bridge_manual "1" and set tosun_db_bridge_enabled "1", without set tosun_db_bridge_money_write "1".

Connect through the existing game server#

The bridge uses the oxmysql connection already running on your FiveM server. The panel sends supported jobs through an HTTPS queue; the game server executes them locally and returns the selected result. You do not need to copy the MySQL password into the website or expose the MySQL port to the internet.

1. The connection is on by default for every server in Servers; with tosun-ac 9.6.14 or later you do not need to enable it. To turn it off for one server, open Servers → the server → Tosun Connect card → Disable connection. If the legacy full mirror is deliberately enabled with ts.panelMirror.enabled = true in configs/anticheat_config.lua, the bridge stays off automatically so the legacy mirror keeps working.
2. With tosun-ac 9.6.14 or later, no server.cfg line is needed for the connection; keep only the set tosun_ac_license line with the correct license. Older tosun_db_bridge_enabled and tosun_db_bridge_money_write lines are then ignored and can be deleted; a server still running an older package needs them until the new package is installed. Online balance editing is also on by default and limited to panel users with the admin or owner role.
3. Allow outbound HTTPS to admin.tosundev.com, then check the server console status and request a small player list from the panel.

# Run in the server console:
tosunac_db_status

Community website with only the license#

Your community website reads game data through the same Tosun Connect connection. If the server has no game database settings in the panel, the website needs no MySQL user, no GRANT and no open port 3306: the Players, Bans, Anticheat detections and Logs pages load their data from the game server when you open them.

This mode cannot search, filter, unban, add bans or edit money and inventories from the website. To remove a ban, use /ts unban <banID> in game or ts unban <banID> in the server console. Every page is a new request answered within about 10 seconds; if the game server is offline or the connection is turned off on the Tosun Connect card, the page says so instead of showing an empty list.

Names, jobs, balances, inventories and vehicle models need tosun-ac 9.6.17 or later on the game server. With older packages some MySQL/MariaDB servers return only the character ID.

A direct game database connection is optional. Add it only if you want search and editing on the website: create a database user that can connect only from the Tosun panel server's IP address (support can confirm it), give it SELECT, INSERT, UPDATE and DELETE on the game database, allow port 3306 only from that address, and enter the details in the server's database settings under Servers (Direct MySQL · Advanced). The panel saves them only after a successful connection test. Without these details the license-only setup stays in use.

• Players: 25 characters per page with character ID, name and job. Staff also see cash and bank.
• Staff (moderator and above) can click a character to see online status, balances and inventory, and load that character's vehicles.
• Bans and anticheat detections: 25 records per page, read only. Detections are listed oldest first; bans follow the ban ID order.
• Dashboard totals for players, bans and detections show “—”: the connection has no counting operation, so no number is guessed.

Know which data is available#

The connection is on by default; apart from set tosun_ac_license, no server.cfg line is needed for it. QBCore/Qbox reads players and player_vehicles; ESX reads users and owned_vehicles; ban and detection reads use ts_anticheat and ac_detections. Supported operations are player lists, one character detail, that character’s vehicles, bans and anticheat logs. These six allowed tables do not cover every framework table; custom stashes, business, housing and banking tables are not automatically discovered.

Inventory results include selected item fields, with a bounded stored inventory blob and at most 100 visited entries. Arbitrary metadata, stashes and every custom table are not mirrored. A truncated inventory is a partial result, not evidence that the missing items do not exist. Use the game’s supported inventory tools for a complete investigation.

Read status without creating load#

When idle, the bridge polls the panel over HTTPS about every 10 seconds without querying the game database. List pages return at most 25 results; character detail returns one. Results are limited to 65,536 bytes and requested schema information is cached for five minutes. No data query runs if the required unique/owner index structure cannot be verified, including missing or unsuitable indexes or more than 64 index metadata rows. unsupported_index does not mean records do not exist; suitable composite indexes are supported for vehicle queries.

• oxmysql_unavailable: check resource start order and the existing connection.
• unsupported_framework or schema_unavailable: check actual framework, table and column compatibility.
• unsupported_index: conditions were not verified and no data query ran. Ask the database maintainer to inspect missing, unsuitable or overflowing index information; do not blindly change production indexes.
• request_expired or stale status: check connectivity and request age before requesting another read.

• Framework compatibility
• Performance measurements

Edit balances only deliberately#

Online balance editing is on by default. Panel users with the admin or owner role (economy permission) can set the cash or bank total of a supported online character after reviewing the confirmation summary. The operation sets an absolute balance; it does not add the same amount on every retry. The expected current balance is checked before applying a change; if it does not match, stale_balance is returned and nothing changes. Every request is written to the audit log.

Offline SQL updates are not a fallback. The bridge retains an uncertain-operation record to prevent an automatic repeat. Do not give the admin or owner role to staff who only need inspection. To stop balance editing on one server, use Disable connection on its Tosun Connect card (this also stops reads), or switch to manual mode with set tosun_db_bridge_manual "1", where tosun_db_bridge_enabled and tosun_db_bridge_money_write are read from server.cfg and each stays off unless set to "1".

1. Read the current character and account balance, confirm the intended final amount and perform one action.
2. If stale_balance appears, read again and reassess; someone may have earned or spent money meanwhile.
3. If unknown_outcome appears, stop and compare live balance and audit records. Do not send another write until you know the first result.

• Credentials and API behavior

Distinguish a saved list from a live character detail#

A player list comes from saved character rows; it is not a continuous live feed. Opening a character detail can replace saved balances with the supported online framework values and, when available, read that player’s current ox_inventory items. Select by persistent character_id, not a remembered session number. In the panel, check unavailable-balance indicators and the incomplete-inventory warning before interpreting zeros or assuming the list is complete. Developers can inspect the corresponding balance_available and inventory_truncated flags. An unavailable field or partial inventory does not prove lost money or missing property. Vehicle results describe selected stored fields and do not establish that a vehicle is currently spawned or belongs to an active garage session.

1. Compare one known character’s detail against the game at a recorded time, including its online state and chosen account.
2. If data disagrees, check character identity, whether the result was a list or detail, and the availability flags before acting.
3. After reconnecting or switching characters, request a fresh detail rather than reusing the previous character’s result.

Paginate investigations instead of requesting a database dump#

The panel queue allows at most three pending or claimed requests per server and twelve new requests per minute. A job has a 120-second lifetime; results are temporary, with cleanup eligible five minutes after request expiry rather than at a guaranteed deletion time. These limits support targeted administration rather than automatic full-database harvesting. Use the panel’s next-page controls; developers should follow has_more and next_cursor only for the same operation and character. An empty next page is different from a failed query. Required unique keys and vehicle-owner indexes are checked so unsupported layouts can stop safely. Do not rename production columns or add an index solely to silence an error without assessing the application and query plan.

1. Read one panel page at a time. In a custom integration, retain its cursor with the operation and continue only when has_more is true.
2. On queue_full or rate_limited, wait for outstanding work rather than repeatedly reopening the same views.
3. Ask the database maintainer to assess unsupported_index on a copy first; schema metadata can remain cached for five minutes.

Pause access without erasing uncertain operations#

For an inspection-only setup, give staff only the needed read permissions; only the admin and owner roles can edit balances. To stop the connection for one server, open Servers → the server → Tosun Connect card and choose Disable connection; this stops all reads and balance edits for that server, and the same card turns it on again. If you need reads without balance editing, use manual mode: add set tosun_db_bridge_manual "1" and set tosun_db_bridge_enabled "1" to server.cfg and leave tosun_db_bridge_money_write unset or at "0". In manual mode both values are read from server.cfg and each stays off unless set to "1", so manual mode without set tosun_db_bridge_enabled "1" stops reads as well. Disabling the panel marks pending or claimed requests failed; a claimed money write is marked unknown_outcome because its effect may already have occurred. The game-side operation ledger is therefore not a disposable cache. Deleting its KVP records to force another attempt can remove evidence that prevents repetition. Also review access to captured player data: the bridge does not make a publicly shared screenshot or exported support log private.

1. Before planned disconnection, let reads finish and investigate any unresolved money result with live balance and audit records.
2. After disabling, verify the panel state and tosunac_db_status; no new queued inspection should be treated as successful.
3. When turning the connection on again from the card, start with one read and do not edit balances until permissions, capabilities and earlier uncertain operations are reviewed.

# Server console / Sunucu konsolu:
tosunac_db_status

Inspect schema compatibility without changing player data#

For schema_unavailable or unsupported_index, first confirm that the database used by the game is selected. The example below reads column names and types only; it does not change balances, inventories or vehicle records. This is not a mandatory installation step. An authorized database administrator investigating a schema error can run it in their existing private database tool. Do not submit SQL text to the panel bridge; the bridge accepts predefined operations only.

QBCore/Qbox player reads require citizenid, money, job and charinfo in players; ESX reads require identifier, accounts and job in users. Finding the table is not sufficient. The character key must have a supported type and a single-column, full-length unique index.

Vehicle reads also check an index layout suited to owner and vehicle keys. This prevents forcing expensive queries. Do not rename a custom garage table to make an error disappear; ask the framework and garage developers to assess compatibility first.

• Record the error code, framework version and affected read operation.
• Compare columns and indexes; omit player rows from support requests.
• Evaluate any required change on a test copy first. The bridge schema cache may not recognize the new structure immediately.

SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND TABLE_NAME IN ('players', 'users', 'player_vehicles', 'owned_vehicles')
ORDER BY TABLE_NAME, ORDINAL_POSITION
LIMIT 128;

A character appears, but the vehicle result is empty#

Suppose a character selected from the player list opens correctly, but their vehicle list is empty. First distinguish a completed successful result from a failed job. A successful empty list means that this read returned no matching records; it does not prove that the player has no vehicle in any system. Do not treat query_failed, schema_unavailable or unsupported_index as an empty list.

Confirm that selection uses the same permanent character_id. A session number that can change after reconnecting cannot replace the character key. QBCore/Qbox matches ownership through player_vehicles.citizenid; ESX uses owned_vehicles.owner. If a custom garage uses another table or owner format, the standard bridge does not discover those records automatically.

Selecting the wrong character on a multi-character account can produce a similar symptom. Ask the authorized garage administrator to verify the game-side record context for one known vehicle. Writing a balance through the bridge, recreating the vehicle or clearing the source table is unnecessary for diagnosis.

• Record server ID, masked character reference, operation time and job status.
• If another page exists, continue with the same character context; do not move a cursor to another character.
• Tell support whether the result was successfully empty or included an exact error code; remove personal player data.

Separate numbers, text and unavailable fields#

The bridge does not display an unchanged raw database row; supported fields are normalized to specific types and lengths. Character money is read from JSON numbers. For example, 1200 and quoted "1200" are different storage types; a custom script converting a money field to text may produce unavailable balance data. An unavailable balance is displayed as — in the panel; this does not mean a zero balance. Selected inventory fields include name, label, count, slot and quality; arbitrary metadata, stash contents and business accounts fall outside that result.

Selected vehicle values such as fuel, engine and state may return as text; do not derive numeric comparisons from formatting alone. Supported char/varchar character-key schema length is at most 96; the transmitted text key is also limited to 96 bytes, which differs for multibyte characters; int, bigint and mediumint are also supported. Do not assume a custom binary key is standard. Long text and inventory may be truncated; omitted information is not deleted information. Ask the developer to verify the actual source format before diagnosing a missing field. Evaluate necessary type conversion against the game data contract in a test environment, rather than changing production data simply to fill a screen.

Close a balance write with a concrete acceptance example#

For an authorized, approved correction, imagine changing an online character cash balance from 1200 to 1250. The target final total is 1250; entering 50 sets the balance to fifty rather than adding fifty. Check the selected cash or bank account and match the persistent character identity to recent live detail. The confirmation summary shows character, account and the change from current to new total. The amount is a non-negative whole final value; custom currencies and business balances are not interchangeable with this operation.

Do not close acceptance when the job enters the queue. Confirm the completed result for the same character and account reports before=1200 and after=1250, then use an ordinary character read to check current state. Subsequent player spending may change that read; a completed result is not a reason to resend automatically. Investigate the obsolete assumption behind stale_balance and the unverified effect behind unknown_outcome. Keep the request identity, time and sanitized result summary. When the outcome is uncertain, send no new write until the actual balance and intended correction have been reassessed.

A response deadline does not cancel SQL#

The default SQL response wait is 5,000 ms. query_timeout ends the panel’s wait; the actual query may still be running. SQL capacity remains occupied until its first real callback, and another read returns query_busy. A late response does not change the previous view. If no callback arrives, the deadline does not automatically free capacity. The server administrator should inspect the connection and database; restarting the resource does not prove SQL cancellation.

Only the server owner may optionally add the following set line to server.cfg. The value is clamped to 1,000–10,000 ms; an invalid or infinite number uses 5,000 ms. This setting does not speed up SQL or automatically retry queries.

Online balance editing is on by default for panel users with the admin or owner role (economy permission); in manual mode (set tosun_db_bridge_manual "1") it stays off unless tosun_db_bridge_money_write is "1". It requires a supported online character and confirmation in the panel. The operation replaces only cash or bank totals after checking the expected current balance; it does not fall back to offline SQL writes. unknown_outcome or a connection ambiguity is never automatically retried. Inspect live balance and audit records before another write; do not delete uncertain-operation KVP records to force a repeat.

set tosun_db_bridge_query_timeout_ms "5000"

One SQL import, with the correct database#

tosun-ac/INSTALL.sql is the single SQL import entry point in the new ZIP. Do not also import an old second copy of the same schema. This SQL belongs in the game database used by FiveM and oxmysql, not in the rented website’s account/theme database. The installer repairs required legacy columns before inserting defaults and retains existing bans and custom settings.

1. Back up the game database and confirm its name against the oxmysql connection.
2. Import INSTALL.sql once in HeidiSQL/phpMyAdmin, or explicitly name the target database in the mysql command.
3. Use tosunac_db_check to check a query and tosunac_db_status for bridge state. The bridge is on by default and needs no server.cfg line. enabled=false is expected in manual mode (set tosun_db_bridge_manual "1") without tosun_db_bridge_enabled "1", or when the legacy full mirror (ts.panelMirror.enabled = true in configs/anticheat_config.lua) is enabled on purpose. A license alone does not establish MySQL connectivity.
4. The panel connection (Tosun Connect) and online balance editing are on by default. Do not add tosun_db_bridge_enabled or tosun_db_bridge_money_write to server.cfg; older lines are ignored from package 9.6.14 on and can be deleted (older packages still need them until you install the current package). Only panel users with the admin or owner role can set balances: the character must be online, the expected balance must match (otherwise stale_balance and nothing changes), the panel shows a confirmation summary before sending, every request is written to the audit log, and an uncertain result is never retried automatically; check the in-game balance first. It sets the total, it does not add. To turn off the whole connection for one server (this stops all panel reads and balance edits), use Panel → Servers → the server → Tosun Connect card → Disable connection; you can turn it on again from the same card. Keep the game database password on the game server.

mysql -u YOUR_DB_USER -p YOUR_GAME_DATABASE < tosun-ac/INSTALL.sql

# txAdmin console:
tosunac_db_check
tosunac_db_status