> For the complete documentation index, see [llms.txt](https://docs.tworst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tworst.com/getting-started-installation/guides/database-setup.md).

# Database Setup

Guide for setting up database tables for Tworst Scripts.

***

## Automatic Setup

{% hint style="success" %}
**Good News!** All Tworst Scripts **automatically create** the required database tables when the script starts for the first time. In most cases, you don't need to do anything manually!
{% endhint %}

When you start your server with a Tworst Script for the first time, the script will:

1. Check if the required tables exist
2. Create any missing tables automatically
3. Set up the correct table structure

**You should see a message in your server console confirming the tables were created.**

***

## Prerequisites

Before the automatic setup can work, make sure you have one of these database resources running:

| Database Resource | Config Value     | Notes          |
| ----------------- | ---------------- | -------------- |
| oxmysql           | `'oxmysql'`      | Recommended    |
| mysql-async       | `'mysql-async'`  | Legacy support |
| ghmattimysql      | `'ghmattimysql'` | Legacy support |

Set your database resource in `config/config.lua`:

```lua
Config.SQL = "oxmysql"  -- Options: 'oxmysql', 'mysql-async', 'ghmattimysql'
```

{% hint style="warning" %}
Make sure your database resource starts **before** any Tworst Scripts in your `server.cfg`.
{% endhint %}

***

## Manual Setup (Optional)

In rare cases where automatic table creation fails, you can manually import the SQL tables.

### When to Use Manual Setup

* Automatic creation failed due to permission issues
* You prefer to review the table structure before creation
* You're migrating from another script

### How to Import Manually

Each Tworst Script includes an `insert.sql` file in the root folder:

```
tw-scriptname/
├── insert.sql  ← SQL file for manual import
├── fxmanifest.lua
├── config/
└── ...
```

#### Method 1: HeidiSQL

1. Connect to your database
2. Select your database from the left panel
3. Go to **File → Run SQL file**
4. Select the `insert.sql` file from the script folder
5. Click **Execute**

#### Method 2: phpMyAdmin

1. Login to phpMyAdmin
2. Select your database from the left panel
3. Go to the **Import** tab
4. Click **Choose File** and select the `insert.sql` file
5. Click **Go**

#### Method 3: Command Line

```bash
mysql -u username -p database_name < insert.sql
```

{% hint style="warning" %}
**Always backup your database** before manually importing tables, especially on production servers.
{% endhint %}

***

## Table Naming Convention

All Tworst Scripts use a consistent naming convention for database tables:

```
tw_[scriptname]_[table]
```

**Examples:**

| Script        | Table Name             |
| ------------- | ---------------------- |
| Scrapyard Job | `tw_scrapyard_players` |
| Gardener Job  | `tw_gardener_players`  |
| Transport Job | `tw_transport_players` |

This naming convention helps you:

* Easily identify which tables belong to which script
* Avoid conflicts with other resources
* Manage your database more efficiently

***

## Common Issues

| Error                | Cause                  | Solution                                                      |
| -------------------- | ---------------------- | ------------------------------------------------------------- |
| Table already exists | Previous installation  | Safe to ignore, or drop existing table if you want fresh data |
| Access denied        | Database permissions   | Check your database user has CREATE TABLE permissions         |
| Unknown database     | Database doesn't exist | Create the database first in your MySQL client                |
| Connection failed    | Wrong credentials      | Verify database credentials in your `server.cfg`              |

### Checking Database Connection

Make sure your `server.cfg` has the correct database connection string:

```cfg
set mysql_connection_string "mysql://user:password@localhost/database_name?charset=utf8mb4"
```

***

## Resetting Data

If you want to reset all data for a script:

{% hint style="danger" %}
**Warning:** This will delete all player progress and data for that script!
{% endhint %}

1. Stop your server
2. Open your database management tool
3. Find the tables starting with `tw_[scriptname]_`
4. Drop (delete) those tables
5. Start your server - tables will be recreated automatically

***

## Need Help?

{% hint style="info" %}
Having database issues? Join our [Discord server](https://discord.gg/tworst) and open a support ticket with:

* Your database resource (oxmysql, mysql-async, etc.)
* The error message from server console
* Your `Config.SQL` setting
  {% endhint %}