sa-mp-mysql Plugin

To install the plugin, follow these steps:

1. Extract the contents of the downloaded archive into the root directory of your SA-MP server.
2. Update your server.cfg file to include the plugin:
   • Windows: Add plugins mysql to the plugins line.
   • Linux: Add plugins mysql.so to the plugins line.

### Windows (server.cfg)
plugins mysql

### Linux (server.cfg)
plugins mysql.so

The plugin must be compiled as a 32-bit library. All required libraries must be 32-bit and the compiler must support 32-bit builds.

Windows Build Requirements

1. A C++ compiler
2. MySQL C Connector (version 6.1.6)
3. Boost libraries (version 1.57 or higher)
4. CMake

Steps:

1. Clone the repository.
2. Create a build folder.
3. Run CMake inside the build folder.
4. Build the generated project files with your C++ compiler.

Linux Build Requirements

1. A C++ compiler
2. MySQL client (version 5.5 or higher) via package manager
3. Boost libraries (version 1.57 or higher)
4. CMake

Steps:

1. Clone the repository.
2. Create a build folder and run CMake: mkdir build && cd build && cmake ..
3. Build the generated project files with your C++ compiler.

# Linux build sequence
mkdir build && cd build && cmake ..

If you encounter issues loading the plugin on Linux, check the following:

• version GLIBCXX_3.4.15' not found: Your system's GCC version is too old. You need a distribution that provides GCC 4.8 or higher (e.g., upgrade from CentOS 6 to CentOS 7).
• Failed (libmysqlclient_r.so.18: cannot open shared object file: No such file or directory): The MySQL client library is missing. Install the 32-bit version (i386, i686, etc.) via your package manager.
• Failed (plugins/mysql.so: symbol __cxa_pure_virtual...): You are likely using a 64-bit libmysqlclient library. You must either install the 32-bit version of the MySQL client package or use the statically linked plugin file: mysql_static.so.
• Missing libmysqlclient installation: If you cannot install the required library on your distribution, use the mysql_static.so plugin instead, as it is statically linked.

If the plugin fails to load on Windows, ensure you have the following x86/32-bit Microsoft C++ redistributables installed:

• 2010
• 2010 SP1
• 2012
• 2015

If you are on an older version of Windows (not Windows 10) and the redistributables do not resolve the issue, download the universal Windows CRT and ensure the following requirements are met:

• Windows 8.1 / Windows Server 2012 R2: KB2919355
• Windows 7 / Windows Server 2008 R2: Service Pack 1
• Windows Vista / Windows Server 2008: Service Pack 2

The CQuery class provides two primary methods for attaching callbacks to handle the outcome of a query execution:

• OnExecutionFinished(function<void(ResultSet_t)> cb): Registers a callback that is triggered when the query execution completes successfully. The callback receives a ResultSet_t.
• OnError(function<void(unsigned int, string)> cb): Registers a callback that is triggered if an error occurs during execution. The callback receives an unsigned int error ID and a string containing the error message.

Note: These callbacks are intended to be called internally via CallCallback() and CallErrorCallback() during the query lifecycle.

The ORM requires a key variable to perform UPDATE, DELETE, or specific SELECT operations. Use SetKeyVariable with the name of the column that acts as the primary key.

// Set 'id' as the primary key for this ORM instance
CError<COrm> error = orm->SetKeyVariable("id");

To execute a SQL query, use the CQuery::Create(string query) factory function to generate a Query_t (a shared pointer to a CQuery instance). You can then call Execute(MYSQL *connection) on the instance to run the query against a specific MySQL connection.

To handle the results or errors asynchronously, you can register callbacks using OnExecutionFinished (for successful results) and OnError (for error handling). After execution, the result set can be retrieved via GetResult().

// Example of creating and executing a query
auto query = CQuery::Create("SELECT * FROM users");

query->OnExecutionFinished([](ResultSet_t result) {
    // Handle the successful result set
});

query->OnError([](unsigned int errorid, string error) {
    // Handle the error
});

bool success = query->Execute(mysql_connection);

Once a query has been executed, use ApplyResult or ApplyResultByName to map the data from a Result_t object back into the registered Pawn variables.

// Apply results from a specific row index to the registered variables
// rowidx defaults to 0
orm->ApplyResult(result, row_index);

// Alternatively, apply by name
bool success = orm->ApplyResultByName(result, row_index);

The CConnectionPool class manages a collection of CThreadedConnection instances. It provides a high-level interface to queue queries across the pool, which is useful for distributing database load and increasing throughput in highly concurrent environments.

// Example usage of CConnectionPool
// Creates a pool of 5 connections
CConnectionPool* pool = new CConnectionPool(5, "host", "user", "pass", "db", options);

// Queue a query to the pool
Query_t query = "INSERT INTO logs (event) VALUES ('login')";
pool->Queue(query);

// Check total unprocessed queries across the entire pool
unsigned int totalPending = pool->GetUnprocessedQueryCount();

The CThreadedConnection class allows you to offload MySQL queries to a dedicated worker thread. This prevents the main SA:MP server thread from blocking while waiting for database responses. You can push queries into a lock-free queue using Queue(), and monitor the workload using GetUnprocessedQueryCount().

// Example usage of CThreadedConnection
CThreadedConnection* threadedConn = new CThreadedConnection("host", "user", "pass", "db", options);

// Queue a query to be processed by the worker thread
Query_t query = "UPDATE players SET score = 100 WHERE id = 1";
if (threadedConn->Queue(query)) {
    // Query is successfully queued
}

// Check how many queries are still waiting in the queue
unsigned int pending = threadedConn->GetUnprocessedQueryCount();