> For the complete documentation index, see [llms.txt](https://donkolia.gitbook.io/minesantum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://donkolia.gitbook.io/minesantum/santumsqltovariable.md).

# SantumSQLtoVariable

{% embed url="<https://youtu.be/AU0ioo9U9Ww?si=sLg1PkFFKnRiev8S>" %}

**SantumSQLtoVariable** is a powerful Minecraft plugin (optimized for Paper 1.21.x) designed to create, manage, and execute highly customized dynamic SQL queries. Its core strength lies in its ability to use Placeholders, perform **real-time math calculations**, and return results either directly via PlaceholderAPI variables or by performing database modifications (INSERT, UPDATE, DELETE)

***

## 🌟 Main Features

1. **Infinite Multi-file System**: You can have as many `.yml` files as you want, organized in as many subfolders as you need.
2. **Native PlaceholderAPI Support**: Inject variables from other plugins (e.g., `%player_name%`, `%vault_eco_balance%`) directly into your SQL queries.
3. **Smart Math Calculations**: It intelligently detects additions, subtractions, multiplications, and divisions alongside your PlaceholderAPI variables and calculates them *before* sending them to the database (e.g., `%player_level%+5`).
4. **Dynamic Commands with Arguments**: Execute your queries from other plugins or the console by sending infinite arguments (`%arg_1%`, `%arg_2%`).
5. **Free SQL Format (Multiline)**: A custom config parser allows you to place your SQL code between parentheses `(` and `)` with any alignment, line breaks, and tabs you want, without throwing YAML errors.
6. **Full DML Support**: Supports read operations (`SELECT`) and modification operations (`INSERT`, `UPDATE`, `DELETE`), returning the number of affected rows for the latter.

***

## 📂 File and Subfolder System

The plugin generates a base folder named `querys` inside `plugins/SantumSQLtoVariable/`. You can create as many subfolders and `.yml` files as you wish. All nodes from all files will be loaded into memory uniformly.

**Structure Example:**

```
plugins/
└── SantumSQLtoVariable/
    └── querys/
        ├── economy.yml
        ├── stats.yml
        └── rewards/
            ├── daily.yml
            └── vip/
                └── monthly.yml
```

***

## 📝 `.yml` File Format

Inside any `.yml` file, you can define as many queries as you want using unique "nodes" (unique names).

**Example (`querys/economy.yml`):**

```yaml
player_money:
    server_ip: localhost
    port: 3306
    user: root
    password: your_password
    database: server_db
    query-start:
    (
        SELECT balance 
        FROM economy 
        WHERE username = '%player_name%'
    )

give_vip_money:
    server_ip: localhost
    port: 3306
    user: root
    password: your_password
    database: server_db
    query-start:
    (
        UPDATE economy 
        SET balance = '%vault_eco_balance%+10000'
        WHERE username = '%player_name%'
    )
```

### Important Rules:

* Each query requires connection parameters. The plugin internally uses a **Connection Pool (HikariCP)**, so if 50 queries point to the same database, they will share the connection, optimizing performance.
* The node name (in the example: `player_money` and `give_vip_money`) will be the query identifier throughout the plugin. Make sure not to repeat node names in other files!
* All SQL syntax must be strictly enclosed between an opening parenthesis `(` and a closing parenthesis `)` on separate lines.

***

## 🧮 Mathematics and Plugin Intelligence

Sometimes you need to add values to a level or subtract money using Placeholders, but MySQL doesn't allow inserting text strings like `'19+1'` into numeric columns.

**SantumSQLtoVariable** automatically detects your intentions. If you write something like `%player_level%+5` inside your SQL query, the plugin internally will:

1. Replace `%player_level%` with the real value (e.g., `19`).
2. Detect the mathematical operation `19+5`.
3. Evaluate the result mathematically using `exp4j` (`24`).
4. Replace the expression in the SQL with the clean number `24` before executing the query in MySQL.

> **Advanced Tip**: If any complex mathematical operation does not have associated PlaceholderAPI variables and you want to force the plugin to calculate it, you can use the explicit tag `{math:your_operation}` (e.g., `{math:10*5}`).

***

## ⚡ Execution and Arguments (`call` Command)

You can execute SQL queries manually or from other plugins using the `call` command. This is especially useful for using it as a reward, punishment, or dynamic saving system.

**Command:** `/santumsqltovariable call insert_reward [argument1] [argument2]`

**Argument Usage Example:** Imagine this query in your `.yml`:

```yaml
insert_reward:
    # ... connection data ...
    query-start:
    (
        INSERT INTO rewards (player, item, amount)
        VALUES ('%player_name%', '%arg_1%', '%arg_2%*2')
    )
```

If you execute the command: `/santumsqltovariable call insert_reward diamond 5` The plugin will translate:

* `%arg_1%` to `diamond`
* `%arg_2%` to `5`
* `%arg_2%*2` mathematically becomes `5*2` and then `10`.

The database will receive: `INSERT INTO rewards (player, item, amount) VALUES ('DonKolia', 'diamond', '10')`.

***

## 🧩 Usage via PlaceholderAPI

To extract visual data from a `SELECT` query and display it on holograms, scoreboards, or in chat, use its native PAPI expansion.

**Format:** `%santumsqltovariable_<node_name>%`

**What happens if the database returns more than one result?** If you run a `SELECT` that returns 5 rows or 3 columns, the plugin will automatically group all responses separated by commas. Example chat response: `result1, result2, result3`.

***

## 🛠️ Commands and Permissions

| Command                                    | Description                                                                 | Permission                  |
| ------------------------------------------ | --------------------------------------------------------------------------- | --------------------------- |
| `/santumsqltovariable reload`              | Reloads all `.yml` files and reconnects databases if they have changed.     | `santumsqltovariable.admin` |
| `/santumsqltovariable call <query> [args]` | Executes a query injecting infinite arguments and PAPI. Console compatible. | `santumsqltovariable.admin` |

*(The plugin includes `Tab` auto-completion to make it easier to find commands and query node names).*

***

*Developed with ❤️ by DonKolia for Paper 1.21.x.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://donkolia.gitbook.io/minesantum/santumsqltovariable.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.