Skip to content

API reference

Every native, forward and constant the plugin exposes, generated from include/mysql_samp.inc.in on every docs build. Nothing here is written by hand, so it cannot drift from what the plugin declares.

Names are listed in the snake_case form that <mysql_samp> declares. The alternative include <mysql_samp_omp> declares the same set under open.mp's Prefix_PascalCase convention, shown beside each signature — aliases only, so the behaviour described here is the behaviour of both.

79 natives, 1 forward and the constants below.

Enumerations

Values are part of the contract — a script may compare against them — so they are read from the include rather than copied here.

Connection options

Constant Value Notes
MYSQL_OPT_PORT 0
MYSQL_OPT_SSL 1
MYSQL_OPT_SSL_CA 2
MYSQL_OPT_CONNECT_TIMEOUT 3
MYSQL_OPT_AUTO_RECONNECT 4
MYSQL_OPT_SSL_CERT 5 Client certificate chain (PEM/DER) for mutual TLS. Needs MYSQL_OPT_SSL_KEY.
MYSQL_OPT_SSL_KEY 6 Client private key (PEM/DER) for mutual TLS. Needs MYSQL_OPT_SSL_CERT.
MYSQL_OPT_SSL_VERIFY_CERT 7 1 (default) verifies the server certificate and hostname. Setting it to 0 keeps the traffic encrypted but accepts ANY certificate, which defeats the point of TLS against an active attacker. Prefer MYSQL_OPT_SSL_CA.
MYSQL_OPT_POOL_SIZE 8 Maximum connections the pool may open. Default is the driver's (max 100).

Memory limits

Constant Value Notes
MYSQL_LIMIT_SAVED_CACHES 0 Saved caches held by cache_save at once. Default 1024.
MYSQL_LIMIT_RESULT_ROWS 1 Rows a single result set may carry. Default 100000.
MYSQL_LIMIT_ORM_STRING_LEN 2 Bytes an ORM string variable may bind. Default 4096.

Error codes

Constant Value
MYSQL_OK 0
MYSQL_ERROR_CONNECTION_FAILED 1
MYSQL_ERROR_INVALID_OPTIONS 2
MYSQL_ERROR_INVALID_CONNECTION 3
MYSQL_ERROR_PING_FAILED 4
MYSQL_ERROR_QUERY_FAILED 5
MYSQL_ERROR_NO_CACHE_ACTIVE 6
MYSQL_ERROR_INVALID_ORM 7
MYSQL_ERROR_ORM_KEY_NOT_SET 8

Log levels

Constant Value
MYSQL_LOG_NONE 0
MYSQL_LOG_ERROR 1
MYSQL_LOG_WARNING 2
MYSQL_LOG_INFO 3
MYSQL_LOG_ALL 4

ORM error codes

Constant Value
ORM_OK 0
ORM_NO_DATA 1

Index

Constants

MYSQL_SAMP_VERSION

#define MYSQL_SAMP_VERSION "1.4.0"

The plugin version this include was generated for.

build.rs stamps it from Cargo.toml on every build, so the value in the include always matches the binary it shipped with. Comparing it at start-up is how a gamemode catches an include left behind by an upgrade.

MYSQL_SYNC

#define MYSQL_SYNC "!sync"

Pass this where a callback name goes to make that ONE call blocking.

Everything in this plugin is non-blocking by default, and that is the right default: a query that waits freezes every player. Sometimes waiting is worth it anyway - schema work in OnGameModeInit, a migration, a one-off console command - and then the alternative is chaining callbacks for something that runs once.

The call runs on the server thread and returns when the database answers. The result is the current cache right after it, so the cache getters read it on the very next line, with no forward and no public.

The result is freed at the next server tick, so read it on the lines right after the call and save it if it has to last longer. A second blocking call within the same frame replaces the first. A failure returns false and fires OnQueryError, the same as the threaded path. See the documentation for worked examples.

NEVER use it in a callback that runs per player or per tick. The whole server stops for as long as the database takes, and that is visible to everyone online.

Forwards

OnQueryError

forward OnQueryError(errorid, const error[], const callback[], const query[], connId);

Fired on every loaded script when a threaded query fails.

Parameter Description
errorid MySQL error code (1062, 1045, ...), or 0 for transport errors
error server error message
callback the callback the query asked for, or "" if none
query the SQL that failed
connId connection that produced the error

Options

mysql_options_new

native mysql_options_new();

In <mysql_samp_omp>: MySQL_OptionsNew

Creates an options handle for a connection.

Returns: the options handle (>= 1), or 0 on failure

mysql_options_set_int

native bool:mysql_options_set_int(handle, option, value);

In <mysql_samp_omp>: MySQL_OptionsSetInt

Sets an integer option (MYSQL_OPT_PORT, MYSQL_OPT_SSL, ...).

Parameter Description
handle an options handle
option a MYSQL_OPT_* value that takes an int
value the value

Returns: true on success, false on a bad handle or type mismatch

mysql_options_set_str

native bool:mysql_options_set_str(handle, option, const value[]);

In <mysql_samp_omp>: MySQL_OptionsSetStr

Sets a string option (MYSQL_OPT_SSL_CA, MYSQL_OPT_SSL_CERT, MYSQL_OPT_SSL_KEY).

Parameter Description
handle an options handle
option a MYSQL_OPT_* value that takes a string
value the value

Returns: true on success, false on a bad handle or type mismatch

Connection

mysql_connect

native mysql_connect(const host[], const user[], const password[], const database[], options = 0);

In <mysql_samp_omp>: MySQL_Connect

Opens a connection pool.

Parameter Description
host hostname, IPv4, IPv6 in brackets ([::1]), or a path starting with / for a unix socket
user MySQL user
password MySQL password
database default schema
options an options handle, or 0 for defaults

Returns: connection id (>= 1), or 0 on failure

mysql_connect_file

native mysql_connect_file(const path[] = "mysql.ini", options = 0);

In <mysql_samp_omp>: MySQL_ConnectFile

Opens a connection reading host/user/password/database from a key = value file, keeping credentials out of the gamemode source.

Parameter Description
path path to the config file
options an options handle, or 0 for defaults

Returns: connection id (>= 1), or 0 on failure

mysql_close

native bool:mysql_close(connId);

In <mysql_samp_omp>: MySQL_Close

Closes a connection and frees its statements and transactions.

Parameter Description
connId connection id

Returns: true on success, false if the id is unknown

mysql_status

native bool:mysql_status(connId, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: MySQL_Status

Writes a short server-status line into dest.

Parameter Description
connId connection id
dest destination buffer
max_len size of dest

Returns: true on success, false on failure

mysql_tls_active

native bool:mysql_tls_active(connId);

In <mysql_samp_omp>: MySQL_TlsActive

Tells whether the session is encrypted, as the handshake settled it.

This is not the same as having asked for TLS with MYSQL_OPT_SSL: the option is the request, and the answer is what the server and the client agreed on. Checking it is how a gamemode verifies its own deployment instead of trusting the option it passed.

Parameter Description
connId connection id

Returns: true when the session is encrypted, false when it is not, when the cipher could not be read, or when the id is unknown

mysql_tls_cipher

native bool:mysql_tls_cipher(connId, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: MySQL_TlsCipher

Writes the cipher suite the session negotiated into dest.

Writes an empty string when the session is not encrypted - that is the answer, not an error. The return value separates it from an unknown id.

Parameter Description
connId connection id
dest destination buffer
max_len size of dest

Returns: true when a cipher was written, false when the session is not encrypted or the id is unknown

Limits

mysql_limit_set

native bool:mysql_limit_set(limit, value);

In <mysql_samp_omp>: MySQL_LimitSet

Raises or lowers one of the memory caps.

The caps exist so a gamemode cannot exhaust the server's memory by accident - a query matching a million rows, a loop saving a cache per tick. They are global, not per connection: the memory being protected is shared.

Lowering a cap below what is already held keeps what is there and refuses the next one, so nothing is thrown away mid-round.

Parameter Description
limit one of the MYSQL_LIMIT_* constants
value the new cap, which must be positive. 0 is refused: it would refuse everything, and there is no "unlimited"

Returns: true when the cap was changed, false on an unknown limit or a value that is not positive

mysql_limit_get

native mysql_limit_get(limit);

In <mysql_samp_omp>: MySQL_LimitGet

Reads a cap, to report it or to restore it later.

Parameter Description
limit one of the MYSQL_LIMIT_* constants

Returns: the current cap, or 0 when the limit is unknown

Error

mysql_errno

native mysql_errno(connId = 0);

In <mysql_samp_omp>: MySQL_Errno

Last error code for a connection.

Parameter Description
connId connection id, or 0 for the global error

Returns: the MySQL error code, a MYSQL_ERROR_* value, or 0 for none

mysql_error

native bool:mysql_error(connId, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: MySQL_Error

Writes the last error message into dest.

Parameter Description
connId connection id, or 0 for the global error
dest destination buffer
max_len size of dest

Returns: true on success, false on failure

Charset

mysql_set_charset

native bool:mysql_set_charset(connId, const charset[]);

In <mysql_samp_omp>: MySQL_SetCharset

Runs SET NAMES to change the connection charset.

Parameter Description
connId connection id
charset charset name (e.g. "utf8mb4")

Returns: true on success, false on failure

mysql_get_charset

native bool:mysql_get_charset(connId, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: MySQL_GetCharset

Reads the connection's current charset into dest.

Parameter Description
connId connection id
dest destination buffer
max_len size of dest

Returns: true on success, false on failure

Utility

mysql_unprocessed_queries

native mysql_unprocessed_queries();

In <mysql_samp_omp>: MySQL_UnprocessedQueries

Number of queries submitted but not yet dispatched to a callback.

Returns: the pending count

mysql_log

native bool:mysql_log(log_level);

In <mysql_samp_omp>: MySQL_Log

Sets the minimum log level at runtime.

Parameter Description
log_level a MYSQL_LOG_* value

Returns: true

Query

mysql_query

native bool:mysql_query(connId, const query[], const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_Query

Runs a query on a worker thread, FIFO-ordered.

Parameter Description
connId connection id
query the SQL
callback callback to fire with the result. Optional: "" (the default) discards the result and fires nothing, or MYSQL_SYNC to make THIS call blocking and read the result on the next line
format types of the extra callback args ("d" int, "f" float, "s" string)

Returns: true if submitted, false on a bad connection

Blocking, for start-up work. Reads on the next line, no callback:

mysql_query(sql, "SELECT COUNT(*) AS n FROM accounts", MYSQL_SYNC);
new total = cache_get_value_name_int(0, "n");

mysql_pquery

native bool:mysql_pquery(connId, const query[], const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_PQuery

Runs a query on a worker thread, parallel: no ordering guarantee.

Parameter Description
connId connection id
query the SQL
callback callback to fire with the result. Optional: "" (the default) discards the result and fires nothing, or MYSQL_SYNC to make THIS call blocking and read the result on the next line
format types of the extra callback args

Returns: true if submitted, false on a bad connection

Blocking. Same as the FIFO native in this mode, since a call that waits has nothing to run in parallel with:

mysql_pquery(sql, "DELETE FROM sessions WHERE stale = 1", MYSQL_SYNC);

mysql_tick

native bool:mysql_tick();

In <mysql_samp_omp>: MySQL_Tick

Drains the dispatch queue manually. You do not need to call this: since rust-samp v3.0.0 the queue is pumped automatically every tick. Kept for backwards compatibility.

Returns: true

mysql_escape_string

native bool:mysql_escape_string(const src[], dest[], max_len = sizeof(dest), connId = 0);

In <mysql_samp_omp>: MySQL_EscapeString

Escapes a string for use inside a single-quoted SQL literal.

Parameter Description
src the raw string
dest destination buffer
max_len size of dest
connId connection whose sql_mode picks the escaping rules; pass the real one when the server may run NO_BACKSLASH_ESCAPES (0 assumes the MySQL default)

Returns: true on success, false on failure

mysql_format

native mysql_format(connId, dest[], max_len, const format[], {Float,_}:...);

In <mysql_samp_omp>: MySQL_Format

Builds a query into dest with printf-style specifiers (%d, %f, %s escaped, %e escaped, %r raw). Truncates at the buffer boundary.

Parameter Description
connId connection whose sql_mode picks the escaping rules
dest destination buffer
max_len size of dest
format the format string

Returns: bytes written into dest

mysql_query_file

native bool:mysql_query_file(connId, const path[], const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_QueryFile

Runs the statements of a .sql file in order on one connection, non-blocking. Split on ; outside literals and comments. NOT transactional: DDL commits implicitly in MySQL, and on failure the statements before it stay applied.

Parameter Description
connId connection id
path path to the .sql file
callback callback to fire with the last statement's result. Optional: "" (the default) discards it, or MYSQL_SYNC to run the whole file on the server thread, in order, before the call returns
format types of the extra callback args

Returns: true if submitted, false on a bad connection or unreadable file

Blocking, which is what schema at start-up wants: the tables exist on the line after, with no callback chain and no race:

mysql_query_file(sql, "schema.sql", MYSQL_SYNC);

Prepared statements

mysql_stmt_new

native mysql_stmt_new(connId, const query[]);

In <mysql_samp_omp>: MySQL_StmtNew

Creates a prepared statement. Use ? for each bound value.

Parameter Description
connId connection id
query the SQL with ? placeholders

Returns: statement id (>= 1), or 0 on a bad connection

mysql_stmt_close

native bool:mysql_stmt_close(stmtId);

In <mysql_samp_omp>: MySQL_StmtClose

Frees a statement.

Parameter Description
stmtId statement id

Returns: true on success, false if the id is unknown

mysql_stmt_reset

native bool:mysql_stmt_reset(stmtId);

In <mysql_samp_omp>: MySQL_StmtReset

Clears the bound values, keeping the statement for reuse.

Parameter Description
stmtId statement id

Returns: true on success, false if the id is unknown

mysql_stmt_bind_int

native bool:mysql_stmt_bind_int(stmtId, value);

In <mysql_samp_omp>: MySQL_StmtBindInt

Binds an integer to the next placeholder.

Parameter Description
stmtId statement id
value the value

Returns: true on success, false if the id is unknown or the limit is reached

mysql_stmt_bind_float

native bool:mysql_stmt_bind_float(stmtId, Float:value);

In <mysql_samp_omp>: MySQL_StmtBindFloat

Binds a float to the next placeholder.

Parameter Description
stmtId statement id
value the value

Returns: true on success, false if the id is unknown or the limit is reached

mysql_stmt_bind_str

native bool:mysql_stmt_bind_str(stmtId, const value[]);

In <mysql_samp_omp>: MySQL_StmtBindStr

Binds a string to the next placeholder.

Parameter Description
stmtId statement id
value the value

Returns: true on success, false if the id is unknown or the limit is reached

mysql_stmt_bind_null

native bool:mysql_stmt_bind_null(stmtId);

In <mysql_samp_omp>: MySQL_StmtBindNull

Binds SQL NULL to the next placeholder.

Parameter Description
stmtId statement id

Returns: true on success, false if the id is unknown or the limit is reached

mysql_stmt_execute

native bool:mysql_stmt_execute(stmtId, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_StmtExecute

Executes a statement, FIFO-ordered. Fails if the number of bound values does not match the number of ? placeholders.

Parameter Description
stmtId statement id
callback callback to fire with the result. Optional: "" (the default) discards the result and fires nothing. MYSQL_SYNC is NOT accepted here
format types of the extra callback args

Returns: true if submitted, false on a bad id or arity mismatch

mysql_stmt_pexecute

native bool:mysql_stmt_pexecute(stmtId, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_StmtPExecute

Executes a statement on a worker thread, parallel: no ordering guarantee.

Parameter Description
stmtId statement id
callback callback to fire with the result. Optional: "" (the default) discards the result and fires nothing. MYSQL_SYNC is NOT accepted here
format types of the extra callback args

Returns: true if submitted, false on a bad id or arity mismatch

Cache

cache_get_row_count

native cache_get_row_count();

In <mysql_samp_omp>: Cache_GetRowCount

Rows in the active result set.

Returns: the row count

cache_get_field_count

native cache_get_field_count();

In <mysql_samp_omp>: Cache_GetFieldCount

Columns in the active result set.

Returns: the field count

cache_get_field_name

native bool:cache_get_field_name(field_idx, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: Cache_GetFieldName

Writes a column's name into dest.

Parameter Description
field_idx column index
dest destination buffer
max_len size of dest

Returns: true on success, false if the index is out of range

cache_get_field_type

native cache_get_field_type(field_idx);

In <mysql_samp_omp>: Cache_GetFieldType

A column's MySQL type (a raw ColumnType byte).

Parameter Description
field_idx column index

Returns: the type byte, or 0 if out of range

cache_get_value_index

native bool:cache_get_value_index(row, col, dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: Cache_GetValueIndex

Reads a cell as a string, by column index.

Parameter Description
row row index
col column index
dest destination buffer
max_len size of dest

Returns: true on success, false if out of range

cache_get_value_index_int

native cache_get_value_index_int(row, col);

In <mysql_samp_omp>: Cache_GetValueIndexInt

Reads a cell as an int, by column index.

Parameter Description
row row index
col column index

Returns: the value, or 0 if out of range or NULL

cache_get_value_index_float

native Float:cache_get_value_index_float(row, col);

In <mysql_samp_omp>: Cache_GetValueIndexFloat

Reads a cell as a float, by column index.

Parameter Description
row row index
col column index

Returns: the value, or 0.0 if out of range or NULL

cache_get_value_name

native bool:cache_get_value_name(row, const field_name[], dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: Cache_GetValueName

Reads a cell as a string, by column name (case-insensitive).

Parameter Description
row row index
field_name column name
dest destination buffer
max_len size of dest

Returns: true on success, false if the row or name is unknown

cache_get_value_name_int

native cache_get_value_name_int(row, const field_name[]);

In <mysql_samp_omp>: Cache_GetValueNameInt

Reads a cell as an int, by column name.

Parameter Description
row row index
field_name column name

Returns: the value, or 0 if unknown or NULL

cache_get_value_name_float

native Float:cache_get_value_name_float(row, const field_name[]);

In <mysql_samp_omp>: Cache_GetValueNameFloat

Reads a cell as a float, by column name.

Parameter Description
row row index
field_name column name

Returns: the value, or 0.0 if unknown or NULL

cache_is_value_index_null

native bool:cache_is_value_index_null(row, col);

In <mysql_samp_omp>: Cache_IsValueIndexNull

Whether a cell is SQL NULL, by column index.

Parameter Description
row row index
col column index

Returns: true if NULL

cache_is_value_name_null

native bool:cache_is_value_name_null(row, const field_name[]);

In <mysql_samp_omp>: Cache_IsValueNameNull

Whether a cell is SQL NULL, by column name.

Parameter Description
row row index
field_name column name

Returns: true if NULL

cache_affected_rows

native cache_affected_rows();

In <mysql_samp_omp>: Cache_AffectedRows

Rows affected by the last INSERT/UPDATE/DELETE.

Returns: the affected-row count

cache_insert_id

native cache_insert_id();

In <mysql_samp_omp>: Cache_InsertId

AUTO_INCREMENT id generated by the last INSERT.

Returns: the insert id

cache_warning_count

native cache_warning_count();

In <mysql_samp_omp>: Cache_WarningCount

Warnings the server raised for the query.

Returns: the warning count

cache_get_query_exec_time

native cache_get_query_exec_time();

In <mysql_samp_omp>: Cache_GetQueryExecTime

How long the query took to execute.

Returns: the time in milliseconds

cache_get_query_string

native bool:cache_get_query_string(dest[], max_len = sizeof(dest));

In <mysql_samp_omp>: Cache_GetQueryString

Writes the query text into dest.

Parameter Description
dest destination buffer
max_len size of dest

Returns: true on success, false on failure

cache_get_result_count

native cache_get_result_count();

In <mysql_samp_omp>: Cache_GetResultCount

Result sets in the active cache. A plain query yields 1; a stored-procedure CALL or a script can yield several.

Returns: the result-set count

cache_set_result

native bool:cache_set_result(result_index);

In <mysql_samp_omp>: Cache_SetResult

Selects which result set the other cache_* natives read (0 until changed).

Parameter Description
result_index result-set index

Returns: true on success, false if the index is out of range

cache_save

native cache_save();

In <mysql_samp_omp>: Cache_Save

Persists the active cache so it can be read after the callback returns.

Returns: a saved-cache id (>= 1), or 0 on failure

cache_delete

native bool:cache_delete(cache_id);

In <mysql_samp_omp>: Cache_Delete

Frees a saved cache.

Parameter Description
cache_id id from cache_save

Returns: true on success, false if the id is unknown

cache_set_active

native bool:cache_set_active(cache_id);

In <mysql_samp_omp>: Cache_SetActive

Makes a saved cache the active one.

Parameter Description
cache_id id from cache_save

Returns: true on success, false if the id is unknown

cache_unset_active

native bool:cache_unset_active();

In <mysql_samp_omp>: Cache_UnsetActive

Clears the manually set active cache.

Returns: true on success, false if none was set

cache_is_any_active

native bool:cache_is_any_active();

In <mysql_samp_omp>: Cache_IsAnyActive

Whether any cache is currently active.

Returns: true if one is active

cache_is_valid

native bool:cache_is_valid(cache_id);

In <mysql_samp_omp>: Cache_IsValid

Whether a saved-cache id is still valid.

Parameter Description
cache_id id from cache_save

Returns: true if valid

ORM

orm_create

native orm_create(const table[], connId);

In <mysql_samp_omp>: ORM_Create

Creates an ORM instance bound to a table.

Parameter Description
table table name
connId connection id

Returns: an ORM id (>= 1), or 0 on a bad connection

orm_destroy

native bool:orm_destroy(orm_id);

In <mysql_samp_omp>: ORM_Destroy

Destroys an ORM instance.

Parameter Description
orm_id ORM id

Returns: true on success, false if the id is unknown

orm_errno

native orm_errno(orm_id);

In <mysql_samp_omp>: ORM_Errno

Last ORM error. Only the apply-cache operation sets it.

Parameter Description
orm_id ORM id

Returns: ORM_OK or ORM_NO_DATA

orm_select

native bool:orm_select(orm_id, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: ORM_Select

SELECTs the row matching the key and fills the bound variables.

Parameter Description
orm_id ORM id
callback callback to fire when done. Optional: "" (the default) runs the operation and fires nothing
format types of the extra callback args

Returns: true if submitted, false on failure

orm_update

native bool:orm_update(orm_id, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: ORM_Update

UPDATEs the row matching the key with the bound variables.

Parameter Description
orm_id ORM id
callback callback to fire when done. Optional: "" (the default) runs the operation and fires nothing
format types of the extra callback args

Returns: true if submitted, false on failure

orm_insert

native bool:orm_insert(orm_id, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: ORM_Insert

INSERTs a row from the bound variables.

Parameter Description
orm_id ORM id
callback callback to fire when done. Optional: "" (the default) runs the operation and fires nothing
format types of the extra callback args

Returns: true if submitted, false on failure

orm_delete

native bool:orm_delete(orm_id, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: ORM_Delete

DELETEs the row matching the key.

Parameter Description
orm_id ORM id
callback callback to fire when done. Optional: "" (the default) runs the operation and fires nothing
format types of the extra callback args

Returns: true if submitted, false on failure

orm_save

native bool:orm_save(orm_id, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: ORM_Save

INSERTs when the key is empty, UPDATEs otherwise.

Parameter Description
orm_id ORM id
callback callback to fire when done. Optional: "" (the default) runs the operation and fires nothing
format types of the extra callback args

Returns: true if submitted, false on failure

orm_apply_cache

native bool:orm_apply_cache(orm_id, row = 0);

In <mysql_samp_omp>: ORM_ApplyCache

Copies a row from the active cache into the bound variables.

Parameter Description
orm_id ORM id
row row index in the active cache

Returns: true on success, false if there is no such row

orm_addvar_int

native bool:orm_addvar_int(orm_id, &var, const column_name[]);

In <mysql_samp_omp>: ORM_AddVarInt

Binds an int variable to a column.

Parameter Description
orm_id ORM id
var the variable (read on write, written on load)
column_name column name

Returns: true on success, false if the id is unknown

orm_addvar_float

native bool:orm_addvar_float(orm_id, &Float:var, const column_name[]);

In <mysql_samp_omp>: ORM_AddVarFloat

Binds a float variable to a column.

Parameter Description
orm_id ORM id
var the variable
column_name column name

Returns: true on success, false if the id is unknown

orm_addvar_string

native bool:orm_addvar_string(orm_id, var[], var_max_len, const column_name[]);

In <mysql_samp_omp>: ORM_AddVarString

Binds a string variable to a column.

Parameter Description
orm_id ORM id
var the buffer
var_max_len size of the buffer (capped at 4096)
column_name column name

Returns: true on success, false on a bad id or length

orm_delvar

native bool:orm_delvar(orm_id, const column_name[]);

In <mysql_samp_omp>: ORM_DelVar

Unbinds a column.

Parameter Description
orm_id ORM id
column_name column name

Returns: true if a binding was removed

orm_clear_vars

native bool:orm_clear_vars(orm_id);

In <mysql_samp_omp>: ORM_ClearVars

Removes all bindings.

Parameter Description
orm_id ORM id

Returns: true on success, false if the id is unknown

orm_setkey

native bool:orm_setkey(orm_id, const column_name[]);

In <mysql_samp_omp>: ORM_SetKey

Sets which bound column is the key for select/update/delete/save.

Parameter Description
orm_id ORM id
column_name column name

Returns: true on success, false if the id is unknown

Password hashing

mysql_hash_password

native bool:mysql_hash_password(const password[], const callback[], const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_HashPassword

Hashes a password with Argon2id, off the server thread.

Parameter Description
password the plaintext
callback callback receiving the PHC hash as its first argument. REQUIRED - the hash is delivered only through it
format types of the extra callback args

Returns: true if queued, false if the callback is empty, the password exceeds 1 KiB, or the work queue is full

mysql_verify_password

native bool:mysql_verify_password(const password[], const hash[], const callback[], const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_VerifyPassword

Verifies a password against a stored PHC hash, off the server thread.

Parameter Description
password the plaintext
hash the stored PHC string
callback callback receiving the bool result as its first argument. REQUIRED - the result arrives only through it
format types of the extra callback args

Returns: true if queued, false if the callback is empty, the password exceeds 1 KiB, or the work queue is full

Transactions

mysql_transaction_new

native mysql_transaction_new(connId);

In <mysql_samp_omp>: MySQL_TransactionNew

Creates a transaction.

Parameter Description
connId connection id

Returns: a transaction id (>= 1), or 0 on a bad connection

mysql_transaction_destroy

native bool:mysql_transaction_destroy(txId);

In <mysql_samp_omp>: MySQL_TransactionDestroy

Discards a transaction that was never executed.

Parameter Description
txId transaction id

Returns: true on success, false if the id is unknown

mysql_transaction_add

native bool:mysql_transaction_add(txId, const query[]);

In <mysql_samp_omp>: MySQL_TransactionAdd

Appends a plain SQL step.

Parameter Description
txId transaction id
query the SQL

Returns: true on success, false if the id is unknown

mysql_transaction_add_stmt

native bool:mysql_transaction_add_stmt(txId, stmtId);

In <mysql_samp_omp>: MySQL_TransactionAddStmt

Appends a prepared statement with its bound values - the safe way to put player input in a transaction. The statement itself is untouched.

Parameter Description
txId transaction id
stmtId statement id

Returns: true on success, false on a bad id or arity mismatch

mysql_transaction_execute

native bool:mysql_transaction_execute(txId, const callback[] = "", const format[] = "", {Float,_}:...);

In <mysql_samp_omp>: MySQL_TransactionExecute

Runs every step atomically, then destroys the transaction (the id is invalid afterwards). The callback receives the cache of the LAST step.

Parameter Description
txId transaction id
callback callback to fire on commit. Optional: "" (the default) commits and fires nothing
format types of the extra callback args

Returns: true if submitted, false on a bad id or empty batch