---
title: "How to Enable the MySQL Module in AMX Mod X"
excerpt: "Enable the MySQL/SQLx module in AMX Mod X, configure sql.cfg, use threaded queries, and fix the connection errors that actually happen."
category: "installation"
tags: "amxmodx, mysql"
image: ""
read_time: "9 min read"
---
<p>AMX Mod X talks to MySQL through the <strong>MySQL module</strong>, which backs the <code>sqlx</code> include. That is what stats plugins, ban systems (AMXBans), shops and VIP systems use to persist data across map changes and across servers. Enabling it is three steps. Using it without freezing your server is the part people get wrong.</p>

<h2>1. Enable the module</h2>
<p>The module ships with the AMX Mod X base package but is commented out by default. Edit <code>addons/amxmodx/configs/modules.ini</code>:</p>
<pre>fun
engine
fakemeta
cstrike
csx
hamsandwich
nvault
mysql</pre>
<p>Uncomment (or add) <code>mysql</code>. Confirm the file exists:</p>
<pre>ls -la /home/steam/hlds/cstrike/addons/amxmodx/modules/mysql_amxx_i386.so
file /home/steam/hlds/cstrike/addons/amxmodx/modules/mysql_amxx_i386.so</pre>
<p>It must be <code>ELF 32-bit LSB shared object, Intel 80386</code>. The module statically carries what it needs to speak the MySQL wire protocol — you do <strong>not</strong> need to install a 32-bit MySQL client library on the host, and trying to is a common wild goose chase.</p>

<h2>2. Configure sql.cfg</h2>
<p><code>addons/amxmodx/configs/sql.cfg</code> holds the default credentials that plugins pick up via <code>get_cvar_string("amx_sql_host")</code> and friends:</p>
<pre>amx_sql_host     "127.0.0.1"
amx_sql_user     "amxx"
amx_sql_pass     "a-real-password"
amx_sql_db       "amxx"
amx_sql_table    "amx_amxbans"
amx_sql_type     "mysql"
amx_sql_timeout  "60"</pre>
<p>Two things that bite:</p>
<ul>
<li><strong><code>127.0.0.1</code> and <code>localhost</code> are not the same to MySQL.</strong> <code>localhost</code> means a Unix socket; <code>127.0.0.1</code> means TCP. Grants are per-host, so <code>'amxx'@'localhost'</code> will not authenticate a TCP connection from <code>'amxx'@'127.0.0.1'</code>. Use <code>127.0.0.1</code> and grant to it.</li>
<li><code>sql.cfg</code> is world-readable if you are careless. It contains a plaintext database password. <code>chmod 640</code> it and make sure the HLDS user owns it.</li>
</ul>

<h2>3. Create the database and user</h2>
<pre>CREATE DATABASE amxx CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'amxx'@'127.0.0.1' IDENTIFIED BY 'a-real-password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX ON amxx.* TO 'amxx'@'127.0.0.1';
FLUSH PRIVILEGES;</pre>
<p>Do not grant <code>ALL PRIVILEGES</code> and do not use <code>root</code>. An AMXX plugin from a forum is not code you have audited; it should not be able to drop your database. If MySQL is on another host, grant to that host's IP and make sure MySQL is not listening on <code>0.0.0.0</code> without a firewall. Setup details: <a href="/tutorials/install-mariadb-for-amxx">MariaDB for AMX Mod X</a>.</p>

<h2>4. Restart and verify</h2>
<p>Modules load at startup, not at map change. Restart, then:</p>
<pre>amxx modules</pre>
<pre>Currently loaded modules:
      name           version     author           status
 [ 6] MySQL          1.9.0.5258  AMXX Dev Team    running</pre>
<p>Then confirm an actual connection. The cleanest test is a plugin that uses the database — install your stats or ban plugin and watch <code>addons/amxmodx/logs/error_*.log</code> at startup. A working connection is silent; a broken one is very loud.</p>

<h2>5. Threaded queries, or your server will freeze</h2>
<p>This is the single most important thing on this page. <code>SQL_Execute()</code> is <strong>blocking</strong>: the entire game loop stops until MySQL answers. On a healthy local socket that is a few milliseconds and you will not notice. When the database is on another host, or under load, or the network hiccups, it is 200ms — and every player on the server just froze for 200ms.</p>
<p>Use the threaded API instead. The pattern:</p>
<pre>#include &lt;amxmodx&gt;
#include &lt;sqlx&gt;

new Handle:g_sqlTuple

public plugin_init()
{
    register_plugin("Example SQL", "1.0", "you")

    new host[64], user[32], pass[32], db[32]
    get_cvar_string("amx_sql_host", host, charsmax(host))
    get_cvar_string("amx_sql_user", user, charsmax(user))
    get_cvar_string("amx_sql_pass", pass, charsmax(pass))
    get_cvar_string("amx_sql_db",   db,   charsmax(db))

    g_sqlTuple = SQL_MakeDbTuple(host, user, pass, db)

    SQL_ThreadQuery(g_sqlTuple, "QueryHandler",
        "CREATE TABLE IF NOT EXISTS players (steamid VARCHAR(32) PRIMARY KEY, points INT DEFAULT 0)")
}

public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime)
{
    if (failstate != TQUERY_SUCCESS)
    {
        log_amx("SQL error %d: %s", errnum, error)
        return
    }
    // read rows here with SQL_ReadResult / SQL_MoreResults
}</pre>
<p>The rules: build the tuple once in <code>plugin_init()</code>, never inside a per-frame or per-spawn handler; always check <code>failstate</code>; never call <code>SQL_FreeHandle()</code> on a handle you did not create in that callback. Getting the last one wrong crashes the server — see <a href="/tutorials/sqlx-threaded-queries">threaded SQLx queries</a>.</p>

<h2>Common errors</h2>
<ul>
<li><strong><code>Access denied for user 'amxx'@'localhost' (using password: YES)</code></strong> — the grant does not match the host MySQL sees you coming from. Grant to <code>'amxx'@'127.0.0.1'</code> and set <code>amx_sql_host</code> to <code>127.0.0.1</code>. Full walkthrough: <a href="/tutorials/fix-mysql-access-denied-amxx">Access denied from an AMXX plugin</a>.</li>
<li><strong><code>Can't connect to MySQL server on '10.0.0.5' (111)</code></strong> — errno 111 is connection refused: MySQL is bound to <code>127.0.0.1</code> only, or a firewall is dropping 3306. See <a href="/tutorials/fix-mysql-cant-connect-111">errno 111</a>.</li>
<li><strong><code>Module failed to load</code> for mysql</strong> — the <code>.so</code> is missing from <code>modules/</code>, or it is 64-bit. Reinstall from the AMXX base package for your exact version.</li>
<li><strong>Server stutters every round</strong> — a plugin using <code>SQL_Execute()</code> on a hot path. Convert it to <code>SQL_ThreadQuery()</code>; see <a href="/tutorials/fix-server-freeze-mysql-query">server freezes on MySQL query</a>.</li>
<li><strong><code>Unknown database 'amxx'</code></strong> — the database name in <code>sql.cfg</code> does not exist. Case matters on Linux.</li>
</ul>

<h2>Verification checklist</h2>
<ol>
<li><code>amxx modules</code> shows MySQL as <code>running</code>.</li>
<li>Your stats/bans plugin creates its tables — check with <code>SHOW TABLES;</code> in the database.</li>
<li>A ban issued in-game appears as a row in MySQL.</li>
<li>Data survives a map change and a server restart.</li>
<li><code>error_*.log</code> has no SQL lines after a full map.</li>
</ol>