API reference¶

Full table of every native and forward exposed by mysql_samp. The plugin registers 75 natives and 1 forward.

Source of truth: include/mysql_samp.inc.in and src/lib.rs.

Constants¶

#define MYSQL_SAMP_VERSION "X.Y.Z"

The literal is regenerated by build.rs from CARGO_PKG_VERSION on every build, so the value shipped in mysql_samp.inc always tracks the version declared in Cargo.toml. This page does not hardcode the current number on purpose — check Cargo.toml or the include itself.

Connection options¶

Constant	Value
`MYSQL_OPT_PORT`	0
`MYSQL_OPT_SSL`	1
`MYSQL_OPT_SSL_CA`	2
`MYSQL_OPT_CONNECT_TIMEOUT`	3
`MYSQL_OPT_AUTO_RECONNECT`	4

Plugin 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

Natives¶

Options (3)¶

Native	Returns	Notes
`mysql_options_new()`	`int`	New options handle (`>= 1`)
`mysql_options_set_int(handle, option, value)`	`bool`	`false` if handle invalid, option unknown, or value out of range
`mysql_options_set_str(handle, option, const value[])`	`bool`	`false` if handle invalid or option not a string option

Connection (3)¶

Native	Returns	Notes
`mysql_connect(const host[], const user[], const password[], const database[], options = 0)`	`int`	Connection id (`>= 1`) or `0` on failure
`mysql_close(connId)`	`bool`	`false` if `connId` does not exist
`mysql_status(connId, dest[], max_len = sizeof(dest))`	`bool`	Writes a subset of `SHOW GLOBAL STATUS` into `dest`

Error (2)¶

Native	Returns	Notes
`mysql_errno(connId = 0)`	`int`	One of `MYSQL_*` codes. `0` reads global state
`mysql_error(connId, dest[], max_len = sizeof(dest))`	`bool`	Always `true` (writes the stored message; empty if no error)

Charset (2)¶

Native	Returns	Notes
`mysql_set_charset(connId, const charset[])`	`bool`	Runs `SET NAMES '<charset>'`
`mysql_get_charset(connId, dest[], max_len = sizeof(dest))`	`bool`	Reads `@@character_set_connection`

Utility (2)¶

Native	Returns	Notes
`mysql_unprocessed_queries()`	`int`	In-flight + pending-ordered count
`mysql_log(log_level)`	`bool`	Atomic; always `true`

Queries (5)¶

Native	Returns	Notes
`mysql_query(connId, const query[], const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	FIFO-ordered threaded query
`mysql_pquery(connId, const query[], const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Parallel threaded query
`mysql_tick()`	`bool`	Drains the dispatch queue manually (back-compat only)
`mysql_escape_string(const src[], dest[], max_len = sizeof(dest), connId = 0)`	`bool`	`connId` selects the escaping rules for the server's `sql_mode`; pass it whenever the server may run `NO_BACKSLASH_ESCAPES`
`mysql_query_file(connId, const path[], const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Runs a `.sql` file's statements in order. Not transactional
`mysql_format(connId, dest[], max_len, const format[], {Float,_}:...)`	`int`	Bytes written into `dest` (truncated to `max_len - 1` at a UTF-8 boundary)

Prepared statements (8)¶

Values are bound server-side over the binary protocol and never enter the SQL text. Prefer these over mysql_format for anything carrying player input.

Native	Returns	Notes
`mysql_stmt_new(connId, const query[])`	`int`	Statement ID, or `0` on failure. `?` placeholders
`mysql_stmt_bind_int(stmtId, value)`	`bool`
`mysql_stmt_bind_float(stmtId, Float:value)`	`bool`
`mysql_stmt_bind_str(stmtId, const value[])`	`bool`
`mysql_stmt_bind_null(stmtId)`	`bool`	Binds SQL `NULL`
`mysql_stmt_reset(stmtId)`	`bool`	Drops bound values, keeps the statement
`mysql_stmt_execute(stmtId, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Non-blocking, FIFO. Fails if bound values ≠ placeholders
`mysql_stmt_pexecute(stmtId, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Parallel counterpart, mirroring `mysql_pquery`
`mysql_stmt_close(stmtId)`	`bool`

Transactions (5)¶

Native	Returns	Notes
`mysql_transaction_new(connId)`	`int`	Transaction ID, or `0` on failure
`mysql_transaction_add(txId, const query[])`	`bool`	Plain SQL step
`mysql_transaction_add_stmt(txId, stmtId)`	`bool`	Copies a prepared statement with its bound values
`mysql_transaction_execute(txId, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Atomic batch; consumes the handle; callback gets the last step's cache
`mysql_transaction_destroy(txId)`	`bool`	Discards a batch that was never executed

Password hashing (2)¶

Both run Argon2id on a bounded worker pool. The result is the first callback argument, followed by the extras described by format.

Native	Returns	Notes
`mysql_hash_password(const password[], const callback[], const format[] = "", {Float,_}:...)`	`bool`	`false` if the queue is full or the password exceeds 1 KiB. Callback receives the PHC hash string
`mysql_verify_password(const password[], const hash[], const callback[], const format[] = "", {Float,_}:...)`	`bool`	Callback receives a `bool`

`mysql_format` specifiers¶

Specifier	Type	Behavior
`%d`, `%i`	int	Decimal
`%f`	float	`{:.4}`
`%s`, `%e`	string	Escaped
`%r`	string	Raw, not escaped
`%%`	literal	`%`

Callback format characters¶

Char	Pawn type
`d`, `i`	int
`f`	float
`s`	string

Anything else is counted as an unknown specifier and logged.

Cache — dimensions and values (12)¶

Native	Returns	Notes
`cache_get_row_count()`	`int`	`-1` if no active cache
`cache_get_field_count()`	`int`	`-1` if no active cache
`cache_get_field_name(field_idx, dest[], max_len = sizeof(dest))`	`bool`	`false` if `field_idx` is negative or out of range
`cache_get_field_type(field_idx)`	`int`	Raw `mysql` `ColumnType` byte, or `-1`
`cache_get_value_index(row, col, dest[], max_len = sizeof(dest))`	`bool`	String cell by index
`cache_get_value_index_int(row, col)`	`int`	Parsed int, `0` on miss
`cache_get_value_index_float(row, col)`	`Float`	Parsed float, `0.0` on miss
`cache_get_value_name(row, const field_name[], dest[], max_len = sizeof(dest))`	`bool`	Column name lookup is case-insensitive
`cache_get_value_name_int(row, const field_name[])`	`int`	Parsed int, `0` on miss
`cache_get_value_name_float(row, const field_name[])`	`Float`	Parsed float, `0.0` on miss
`cache_is_value_index_null(row, col)`	`bool`	`true` for NULL and for out-of-range
`cache_is_value_name_null(row, const field_name[])`	`bool`	`true` for NULL and for unknown column

Cache — write-result and query metadata (5)¶

Native	Returns	Notes
`cache_affected_rows()`	`int`	`-1` if no active cache
`cache_insert_id()`	`int`	`-1` if no active cache
`cache_warning_count()`	`int`	`-1` if no active cache
`cache_get_query_exec_time()`	`int`	Milliseconds, `-1` if no active cache
`cache_get_query_string(dest[], max_len = sizeof(dest))`	`bool`	The exact SQL sent to the server

Cache — persistence (6)¶

Native	Returns	Notes
`cache_save()`	`int`	Saved id (`>= 1`) or `0` if no active cache or limit (1024) hit
`cache_delete(cache_id)`	`bool`	Also clears the manual override if the deleted id was active
`cache_set_active(cache_id)`	`bool`	`false` if `cache_id` does not exist
`cache_unset_active()`	`bool`	`false` if there is no manual override
`cache_is_any_active()`	`bool`	Stack top or manual override
`cache_is_valid(cache_id)`	`bool`	Saved entry exists

ORM (15)¶

Native	Returns	Notes
`orm_create(const table[], connId)`	`int`	ORM id (`>= 1`) or `0` if `connId` invalid
`orm_destroy(orm_id)`	`bool`	`false` if `orm_id` does not exist
`orm_errno(orm_id)`	`int`	`ORM_OK` or `ORM_NO_DATA`. `-1` if `orm_id` invalid. Only updated by `orm_apply_cache`
`orm_select(orm_id, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Threaded SELECT
`orm_update(orm_id, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Threaded UPDATE
`orm_insert(orm_id, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Threaded INSERT
`orm_delete(orm_id, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	Threaded DELETE
`orm_save(orm_id, const callback[] = "", const format[] = "", {Float,_}:...)`	`bool`	INSERT if key is empty (`0`, `0.0`, `""`), UPDATE otherwise
`orm_apply_cache(orm_id, row = 0)`	`bool`	Sets `orm_errno` to `ORM_NO_DATA` if `row` is invalid
`orm_addvar_int(orm_id, &var, const column_name[])`	`bool`	Stores the AMX address of `var`
`orm_addvar_float(orm_id, &Float:var, const column_name[])`	`bool`	Stores the AMX address of `var`
`orm_addvar_string(orm_id, var[], var_max_len, const column_name[])`	`bool`	`1 <= var_max_len <= 4096`
`orm_delvar(orm_id, const column_name[])`	`bool`	`false` if no binding matched
`orm_clear_vars(orm_id)`	`bool`	Always `true` if `orm_id` exists
`orm_setkey(orm_id, const column_name[])`	`bool`	Always `true` if `orm_id` exists

Forwards (1)¶

Forward	Fired when
`OnQueryError(errorid, const error[], const callback[], const query[], connId)`	A threaded query (`mysql_query` / `mysql_pquery` and the ORM CRUD natives that wrap them) failed

Counts¶

Category	Count
Options	3
Connection	4
Error	2
Charset	2
Utility	2
Queries	6
Prepared statements	9
Transactions	5
Password hashing	2
Cache	25
ORM	15
Total natives	75
Forwards	1