# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tworst.com/getting-started-installation/guides/database-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.