DominScript wrapper around the libmariadb C client API. Verb
nomenclature mirrors the C API names 1:1, so anyone who knows
mysql_real_connect / mysql_query /
mysql_store_result recognises every verb instantly.
Backend and loading
libmariadb is the default backend (its C client API is the recognised MariaDB/MySQL client interface); the API-compatible MySQL/Oracle client library is accepted as a fallback. The library is loaded at runtime (dlopen / LoadLibraryA), not linked at build time — the same pattern as the sqlite, tls, sdl2 and opengl plugins. Without a client library installed, mysql.RealConnect reports a clear error and everything else in the host keeps working.
Handle model
Connections and result sets are separate handles. A connection handle comes from mysql.RealConnect; a result handle comes from mysql.StoreResult after a SELECT-style query. Each handle is single-owner (the plugin-family convention). The row cursor lives inside the result handle: mysql.FetchRow advances it, and the RowString / RowInt / RowIsNull accessors read columns of the current row without re-fetching.
Connection lifecycle
Opening, checking, configuring, and closing a connection.
mysql.RealConnect
mysql.RealConnect($Host, $Port, $User, $Pass, $Db, $Socket) -> i64 conn | 0
Opens a connection (mirror of mysql_real_connect). Returns a positive connection handle, or 0 on failure. Empty strings / 0 select the client library defaults; to connect over a Unix socket, pass the socket path and leave host empty.
| Parameter | Type | Description |
|---|---|---|
| Host | string | Server host; "" = library default / socket. |
| Port | int | TCP port; 0 = default. |
| User | string | User name. |
| Pass | string | Password; "" = none. |
| Db | string | Initial database; "" = none. |
| Socket | string | Unix socket path; "" = none. |
mysql.Ping
mysql.Ping($Conn) -> i32 0|err
Liveness check (mirror of mysql_ping); 0 when the server is reachable.
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
mysql.SetCharacterSet
mysql.SetCharacterSet($Conn, $Charset) -> i32 0|err
Sets the connection character set, e.g. "utf8mb4" (mirror of mysql_set_character_set); 0 on success.
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
| Charset | string | Character-set name. |
mysql.SelectDb
mysql.SelectDb($Conn, $Db) -> i32 0|err
Switches the default database for the connection (mirror of mysql_select_db).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
| Db | string | Database name. |
mysql.Close
mysql.Close($Conn) -> i32 0
Closes the connection and frees the handle (mirror of mysql_close).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
Statements and errors
Running SQL and inspecting the outcome.
mysql.Query
mysql.Query($Conn, $Sql) -> i32 0|err
Executes an SQL statement (mirror of mysql_query); 0 on success. After a SELECT-style statement, call mysql.StoreResult to materialise the rows.
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
| Sql | string | SQL statement text. |
mysql.Error
mysql.Error($Conn) -> string
The last error message on the connection (mirror of mysql_error); "" when there is none.
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
mysql.Errno
mysql.Errno($Conn) -> i32
The last error code on the connection (mirror of mysql_errno); 0 when there is none.
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
Check Errno after Query / StoreResult; a non-zero value means the Error text explains what went wrong.
mysql.AffectedRows
mysql.AffectedRows($Conn) -> i64
Rows changed by the last INSERT / UPDATE / DELETE (mirror of mysql_affected_rows).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
mysql.InsertId
mysql.InsertId($Conn) -> i64
The AUTO_INCREMENT id generated by the last INSERT (mirror of mysql_insert_id).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
mysql.RealEscapeString
mysql.RealEscapeString($Conn, $Str) -> string
Escapes a string for safe embedding in SQL, using the connection's character set (mirror of mysql_real_escape_string).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
| Str | string | Raw text to escape. |
Escape every piece of untrusted text before formatting it into SQL.
Result sets
Materialising rows client-side and reading them.
mysql.StoreResult
mysql.StoreResult($Conn) -> i64 result | 0
Materialises the full result set of the last SELECT client-side and returns a result handle (mirror of mysql_store_result).
| Parameter | Type | Description |
|---|---|---|
| Conn | int | Connection handle. |
mysql.NumRows
mysql.NumRows($Result) -> i64
Number of rows in the stored result (mirror of mysql_num_rows).
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
mysql.NumFields
mysql.NumFields($Result) -> i32
Number of columns in the stored result (mirror of mysql_num_fields).
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
mysql.FieldName
mysql.FieldName($Result, $Index) -> string
The name of a column from the result's schema, by 0-based index.
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
| Index | int | 0-based column index. |
mysql.FetchRow
mysql.FetchRow($Result) -> i32 1|0
Advances the row cursor (mirror of mysql_fetch_row); 1 while a row is available, 0 at the end. The fetched row stays current for the Row* accessors.
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
mysql.RowString
mysql.RowString($Result, $Index) -> string
The current row's column as text; "" for NULL (use mysql.RowIsNull to distinguish).
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
| Index | int | 0-based column index. |
mysql.RowInt
mysql.RowInt($Result, $Index) -> i64
The current row's column parsed as an integer.
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
| Index | int | 0-based column index. |
mysql.RowIsNull
mysql.RowIsNull($Result, $Index) -> i32 1|0
1 when the current row's column is SQL NULL.
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
| Index | int | 0-based column index. |
mysql.FreeResult
mysql.FreeResult($Result) -> i32 0
Releases the stored result set (mirror of mysql_free_result).
| Parameter | Type | Description |
|---|---|---|
| Result | int | Result handle. |
Worked example
plugin "builtin:string";
plugin "../plugins/mysql/MySqlPlugin";
plugin "../plugins/print/PrintPlugin";
void main()
{
i64 $C = mysql.RealConnect("127.0.0.1", 3306, "user", "password", "shop", "");
if ($C <= 0) { printf("connect failed\n"); return; }
mysql.SetCharacterSet($C, "utf8mb4");
string $Safe[32] = mysql.RealEscapeString($C, "O'Brien");
string $Sql[128] = string.Format("INSERT INTO people(name) VALUES('%s')", $Safe);
mysql.Query($C, $Sql);
printf("inserted id=%d\n", mysql.InsertId($C));
mysql.Query($C, "SELECT id, name FROM people ORDER BY id");
i64 $R = mysql.StoreResult($C);
while (mysql.FetchRow($R) == 1)
{
printf("row id=%d name=%s\n", mysql.RowInt($R, 0), mysql.RowString($R, 1));
}
mysql.FreeResult($R);
mysql.Close($C);
}