tinymux/mux/SQL.md

author	date	title
Brazil	March 2026	SQL

TinyMUX 2.14 supports both asynchronous and synchronous SQL. The synchronous/in-line support is similar to that of PennMUSH and TinyMUSH, namely the sql() function. The asynchronous support is unique to TinyMUX at this time and is the recommended method for SQL access.

Asynchronous SQL

1. To enable this functionality, you will need to pass --enable-stubslave to the configure script. If your MySQL is not in the default location (namely, /usr/include/mysql and /usr/lib/mysql), then you will need to tell configure where to find the headers and libraries with the --with-mysql-include and --with-mysql-libs options. For instance:

   ./configure --enable-stubslave \
               --with-mysql-include=/usr/local/mysql/include \
               --with-mysql-libs=/usr/local/mysql/lib
   

2. Once the game has been compiled you will need to add six configuration options to the .conf file. You can check the wizhelp file for more information regarding the options. The six are listed below:

   module sqlproxy
   module sqlslave local
   sql_database <name of database>
   sql_server <localhost or address>
   sql_user <MySQL username>
   sql_password <MySQL password>
   

3. Start the game and check the log file. You should see entries like the following:

   MUX NET/STUB : Stub slave started on fd 3
   MUX INI/LOAD : Registered netmux modules.
   MUX INI/LOAD : Opened interface for StubSlave management.
   

   To perform MySQL queries you will use the @query command in conjunction with the rsrelease(), rserror(), rsprev(), rsrecnext(), rsrows(), rsrec(), rsnext() and rsrecprev() functions. Here's an example:

   &FOO.TR me=
     @if rserror()=
     {
       @pemit %#=Rows: [rsrows()];
       @if rsrows()=
       {
         @trig me/bar.tr
       }
     },
     {
       @pemit %#=Error: [rserror()]
     }
   
   &BAR.TR me=
     @pemit %#=rsrec(|);
     @if rsnext()=
     {
       @trig me/bar.tr
     }
   
   @query/sql me/foo.tr=/show databases;
   

4. This method will allow SQL queries to occur without blocking the main game process. If the SQL is on another machine, slow or even has been disabled or crashed then the game will not hang while waiting on the result to be returned.

In-Line/Synchronous SQL

1. To enable this functionality, you will need to pass --enable-inlinesql to the configure script. If your MySQL is not in the default location (namely, /usr/include/mysql and /usr/lib/mysql), then you will need to tell configure where to find the headers and libraries with the --with-mysql-include and --with-mysql-libs options. For instance:

   ./configure --enable-inlinesql \
               --with-mysql-include=/usr/local/mysql/include \
               --with-mysql-libs=/usr/local/mysql/lib
   

2. Once the game has been compiled you will need to add four configuration options to the .conf file. The four are listed below:

   sql_database <name of database>
   sql_server <localhost or address>
   sql_user <MySQL username>
   sql_password <MySQL password>
   

3. Start the game and check the log file. You should see entries like the following:

   SQL/CONN : Connecting: <database>@<address> as <user>
   SQL/CONN : Connected to MySQL
   

   You can use the sql() function to perform MySQL queries. See help sql().

4. The SQL code enabled with --enable-inlinesql runs synchronous with the TinyMUX process. That means that in the game when you use the sql() function to make a query, the whole game waits on the query to finish. If you're on a server which is not overloaded and has good, free resources and where the MySQL server is running on the same machine then this should not be a problem as long as the MySQL server remains running. If the server is overloaded and therefore slow or if the MySQL server is on a different machine, then there can be a delay in getting the results. That delay will mean the whole game hangs while waiting.

   When using the in-line SQL functionality bear this potential problem in mind. You should test your game with the SQL functionality first before using it in a live environment.