> 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/santumplaceholderstosql.md).

# SantumPlaceholdersToSQL

{% embed url="<https://www.youtube.com/watch?v=-IDydy9-pJQ>" %}

An advanced and highly optimized Minecraft Paper 1.21 plugin that bridges the gap between PlaceholderAPI and MySQL.

This plugin captures specific PlaceholderAPI values from all online players and continuously synchronizes them to a remote MySQL database.

## ⚡ High-Performance Synchronization System

One of the biggest challenges when saving data for hundreds of players is the impact on the server's main thread (TPS drop and lag). We engineered a bulletproof synchronization system to guarantee smooth operation even if your server has 1000 active users at the exact same time.

* **In-Memory Caching**: The plugin stores the last known values of every tracked variable in local memory
* **Differential Updates**: Instead of spamming the database with update queries every 5 seconds, the plugin compares the newly fetched placeholders against the cache
* **Zero-Waste Queries**: A database update is ONLY triggered if the placeholder value has actually changed since the last check
* **Asynchronous Execution**: While the placeholders must be fetched on the main thread, all database connections, calculations, and queries are dispatched to an async background thread
* **Batch Processing**: When updates are required, they are grouped into a single SQL `Batch` execution, massively reducing network overhead
* **HikariCP Pool**: We bundle HikariCP to manage database connections with lightning speed and efficiency

## 🗄️ Database Table Structure

The plugin will automatically create a table named `player_placeholders` in your database.

It uses a composite primary key structure and `ON DUPLICATE KEY UPDATE` to ensure the table only stores the latest data without duplicates.

| Column          | Type         | Description                                    | Example                                |
| --------------- | ------------ | ---------------------------------------------- | -------------------------------------- |
| **fulluuid**    | VARCHAR(36)  | The player's standard UUID with dashes         | `ef14ae69-fb9b-400c-8010-1a3c2456f1c8` |
| **trimmeduuid** | VARCHAR(32)  | The player's UUID without dashes               | `ef14ae69fb9b400c80101a3c2456f1c8`     |
| **username**    | VARCHAR(16)  | The player's current username                  | `DonKolia`                             |
| **variable**    | VARCHAR(255) | The placeholder name (stripped of `%` symbols) | `player_world`                         |
| **valor**       | TEXT         | The actual output/value of the placeholder     | `world`                                |

{% hint style="info" %}
The `%` symbols are automatically stripped from the placeholder strings when saving to the database to keep your column data clean (e.g `%vault_eco_balance%` becomes `vault_eco_balance`).
{% endhint %}

## ⚙️ Configuration Files

### `config.yml`

Handles your MySQL credentials and the global synchronization interval.

```yaml
mysql:
  servidor: "localhost"
  puerto: 3306
  base_de_datos: "minecraft"
  usuario: "root"
  contraseña: ""
  
# How often (in seconds) the server checks for changes
check-time: 5
```

### `variables.yml`

Defines the list of placeholders the plugin will track for every player.

```yaml
variables:
  - "%player_name%"
  - "%vault_eco_balance%"
```

## 🛠️ Commands & Permissions

* `/pts reload` - Reloads the configuration files and reconnects to the database
* `/pts add <variable>` - Dynamically adds a new placeholder to track and saves it to `variables.yml`

**Permission Required**: `placeholderstosql.admin`


---

# 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/santumplaceholderstosql.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.