diff --git a/mysql.md b/mysql.md index 4f71692..d70d4d9 100644 --- a/mysql.md +++ b/mysql.md @@ -171,8 +171,8 @@ print_help'CONCAT%' ## Connections -## `mysql.connect(host, [user], [pass], [db], [charset], [port]) -> conn` -## `mysql.connect(options_t) -> conn` +### `mysql.connect(host, [user], [pass], [db], [charset], [port]) -> conn` +### `mysql.connect(options_t) -> conn` Connect to a mysql server, optionally selecting a working database and charset. @@ -187,32 +187,32 @@ can have the following fields: * `attrs`: a table of form `{attr = value, ...}` containing attributes to be passed to the server per [mysql_options4()](http://dev.mysql.com/doc/refman/5.7/en/mysql-options4.html) * `key`, `cert`, `ca`, `cpath`, `cipher`: parameters used to establish a [SSL connection](http://dev.mysql.com/doc/refman/5.7/en/mysql-ssl-set.html) -## `conn:close()` +### `conn:close()` Close a mysql connection freeing all associated resources (otherwise called when `conn` is garbage collected). ## Queries -## `conn:query(s)` +### `conn:query(s)` Execute a query. If the query string contains multiple statements, only the first statement is executed (see the section on multiple statements). -## `conn:escape(s) -> s` +### `conn:escape(s) -> s` Escape a value to be safely embedded in SQL queries. Assumes the current charset. ## Fetching results -## `conn:store_result() -> result` +### `conn:store_result() -> result` Fetch all the rows in the current result set from the server and return a result object to read them one by one. -## `conn:use_result() -> result` +### `conn:use_result() -> result` Return a result object that will fetch the rows in the current result set from the server on demand. -## `result:fetch([mode[, row_t]]) -> true, v1, v2, ... | row_t | nil` +### `result:fetch([mode[, row_t]]) -> true, v1, v2, ... | row_t | nil` Fetch and return the next row of values from the current result set. Returns nil if there are no more rows to fetch. @@ -235,70 +235,70 @@ Fetch and return the next row of values from the current result set. Returns nil * bit types are returned as Lua numbers, and as `uint64_t` for bit types larger than 48 bits. * enum and set types are always returned as strings. -## `result:rows([mode[, row_t]]) -> iterator() -> row_num, val1, val2, ...` -## `result:rows([mode[, row_t]]) -> iterator() -> row_num, row_t` +### `result:rows([mode[, row_t]]) -> iterator() -> row_num, val1, val2, ...` +### `result:rows([mode[, row_t]]) -> iterator() -> row_num, row_t` Convenience iterator for fetching (or refetching) all the rows from the current result set. The `mode` arg is the same as for `result:fetch()`, with the exception that in unpacked mode, the first `true` value is not present. -## `result:free()` +### `result:free()` Free the result buffer (otherwise called when `result` is garbage collected). -## `result:row_count() -> n` +### `result:row_count() -> n` Return the number of rows in the current result set . This value is only correct if `result:store_result()` was previously called or if all the rows were fetched, in other words if `result:eof()` is true. -## `result:eof() -> true | false` +### `result:eof() -> true | false` Check if there are no more rows to fetch. If `result:store_result()` was previously called, then all rows were already fetched, so `result:eof()` always returns `true` in this case. -## `result:seek(row_number)` +### `result:seek(row_number)` Seek back to a particular row number to refetch the rows from there. ## Query info -## `conn:field_count() -> n` -## `conn:affected_rows() -> n` -## `conn:insert_id() -> n` -## `conn:errno() -> n` -## `conn:sqlstate() -> s` -## `conn:warning_count() -> n` -## `conn:info() -> s` +### `conn:field_count() -> n` +### `conn:affected_rows() -> n` +### `conn:insert_id() -> n` +### `conn:errno() -> n` +### `conn:sqlstate() -> s` +### `conn:warning_count() -> n` +### `conn:info() -> s` Return various pieces of information about the previously executed query. ## Field info -## `result:field_count() -> n` -## `result:field_name(field_number) -> s` -## `result:field_type(field_number) -> type, length, decimals, unsigned` -## `result:field_info(field_number) -> info_t` -## `result:fields() -> iterator() -> i, info_t` +### `result:field_count() -> n` +### `result:field_name(field_number) -> s` +### `result:field_type(field_number) -> type, length, decimals, unsigned` +### `result:field_info(field_number) -> info_t` +### `result:fields() -> iterator() -> i, info_t` Return information about the fields (columns) in the current result set. ## Result bookmarks -## `result:tell() -> bookmark` +### `result:tell() -> bookmark` Get a bookmark to the current row to be later seeked into with `seek()`. -## `result:seek(bookmark)` +### `result:seek(bookmark)` Seek to a previous saved row bookmark, or to a specific row number, fetching more rows as needed. ## Multiple statement queries -## `conn:next_result() -> true | false` +### `conn:next_result() -> true | false` Skip over to the next result set in a multiple statement query, and make that the current result set. Return true if there more result sets after this one. -## `conn:more_results() -> true | false` +### `conn:more_results() -> true | false` Check if there are more result sets after this one. @@ -322,64 +322,64 @@ The flow for prepared statements is like this: * call `fields:get()` to read the values of the fetched row. * call `stmt:close()` to free the statement object and all the associated resources from the server and client. -## `conn:prepare(query) -> stmt, params` +### `conn:prepare(query) -> stmt, params` Prepare a query for multiple execution and return a statement object. -## `stmt:param_count() -> n` +### `stmt:param_count() -> n` Number of parameters. -## `stmt:exec()` +### `stmt:exec()` Execute a prepared statement. -## `stmt:store_result()` +### `stmt:store_result()` Fetch all the rows in the current result set from the server, otherwise the rows are fetched on demand. -## `stmt:fetch() -> true | false | true, 'truncated'` +### `stmt:fetch() -> true | false | true, 'truncated'` Fetch the next row from the current result set. Use a binding buffer (see prepared statements I/O section) to get the row values. If present, second value indicates that at least one of the rows were truncated because the receiving buffer was too small for it. -## `stmt:free_result()` +### `stmt:free_result()` Free the current result and all associated resources (otherwise the result is closed when the statement is closed). -## `stmt:close()` +### `stmt:close()` Close a prepared statement and free all associated resources (otherwise the statement is closed when garbage collected). -## `stmt:next_result()` +### `stmt:next_result()` Skip over to the next result set in a multiple statement query. -## `stmt:row_count() -> n` -## `stmt:affected_rows() -> n` -## `stmt:insert_id() -> n` -## `stmt:field_count() -> n` -## `stmt:errno() -> n` -## `stmt:sqlstate() -> s` -## `stmt:result_metadata() -> result` -## `stmt:fields() -> iterator() -> i, info_t` +### `stmt:row_count() -> n` +### `stmt:affected_rows() -> n` +### `stmt:insert_id() -> n` +### `stmt:field_count() -> n` +### `stmt:errno() -> n` +### `stmt:sqlstate() -> s` +### `stmt:result_metadata() -> result` +### `stmt:fields() -> iterator() -> i, info_t` Return various pieces of information on the executed statement. -## `stmt:reset()` +### `stmt:reset()` See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-reset.html). -## `stmt:seek(row_number)` -## `stmt:tell() -> bookmark` -## `stmt:seek(bookmark)` +### `stmt:seek(row_number)` +### `stmt:tell() -> bookmark` +### `stmt:seek(bookmark)` Seek into the current result set. ## Prepared statements I/O -## `stmt:bind_params(type1, ... | types_t) -> params` +### `stmt:bind_params(type1, ... | types_t) -> params` Bind query parameters according to a list of type definitions (which can be given either packed or unpacked). Return a binding buffer object to be used for setting parameters. @@ -390,11 +390,11 @@ The types must be valid, fully specified SQL types, eg. * `bit(32)` specifies a 32bit bit field * `varchar(200)` specifies a 200 byte varchar. -## `params:set(i, number | int64_t | uint64_t | true | false)` -## `params:set(i, s[, size])` -## `params:set(i, cdata, size)` -## `params:set(i, {year=, month=, ...})` -## `params:set_date(i, [year], [month], [day], [hour], [min], [sec], [frac])` +### `params:set(i, number | int64_t | uint64_t | true | false)` +### `params:set(i, s[, size])` +### `params:set(i, cdata, size)` +### `params:set(i, {year=, month=, ...})` +### `params:set_date(i, [year], [month], [day], [hour], [min], [sec], [frac])` Set a parameter value. @@ -403,11 +403,11 @@ Set a parameter value. * the last forms are for setting date/time/datetime/timestamp fields. * the null type cannot be set (raises an error if attempted). -## `stmt:write(param_number, data[, size])` +### `stmt:write(param_number, data[, size])` Send a parameter value in chunks (for long, var-sized values). -## `stmt:bind_result([type1, ... | types_t | maxsize]) -> fields` +### `stmt:bind_result([type1, ... | types_t | maxsize]) -> fields` Bind result fields according to a list of type definitions (same as for params). Return a binding buffer object to be used for getting row values. @@ -415,91 +415,91 @@ If no types are specified, appropriate type definitions will be created automati Variable-sized fields will get a buffer sized according to data type's maximum allowed size and `maxsize` (which defaults to 64k). -## `fields:get(i) -> value` -## `fields:get_datetime(i) -> year, month, day, hour, min, sec, frac` +### `fields:get(i) -> value` +### `fields:get_datetime(i) -> year, month, day, hour, min, sec, frac` Get a row value from the last fetched row. The same type conversions as for `result:fetch()` apply. -## `fields:is_null(i) -> true | false` +### `fields:is_null(i) -> true | false` Check if a value is null without having to get it if it's not. -## `fields:is_truncated(i) -> true | false` +### `fields:is_truncated(i) -> true | false` Check if a value was truncated due to insufficient buffer space. -## `stmt:bind_result_types([maxsize]) -> types_t` +### `stmt:bind_result_types([maxsize]) -> types_t` Return the list of type definitions that describe the result of a prepared statement. ## Prepared statements settings -## `stmt:update_max_length() -> true | false` -## `stmt:set_update_max_length(true | false)` -## `stmt:cursor_type() -> mysql.C.MYSQL_CURSOR_TYPE_*` -## `stmt:set_cursor_type('CURSOR_TYPE_...')` -## `stmt:set_cursor_type(mysql.C.MYSQL_CURSOR_TYPE_...)` -## `stmt:prefetch_rows() -> n` -## `stmt:set_prefetch_rows(stmt, n)` +### `stmt:update_max_length() -> true | false` +### `stmt:set_update_max_length(true | false)` +### `stmt:cursor_type() -> mysql.C.MYSQL_CURSOR_TYPE_*` +### `stmt:set_cursor_type('CURSOR_TYPE_...')` +### `stmt:set_cursor_type(mysql.C.MYSQL_CURSOR_TYPE_...)` +### `stmt:prefetch_rows() -> n` +### `stmt:set_prefetch_rows(stmt, n)` See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-attr-set.html) for these. ## Connection info -## `conn:set_charset(charset)` +### `conn:set_charset(charset)` Change the current charset. -## `conn:select_db(dbname)` +### `conn:select_db(dbname)` Change the current database. -## `conn:change_user(user, [pass], [db])` +### `conn:change_user(user, [pass], [db])` Change the current user and optionally select a database. -## `conn:set_multiple_statements(true | false)` +### `conn:set_multiple_statements(true | false)` Enable or disable support for query strings containing multiple statements separated by a semi-colon. -## `conn:charset() -> s` +### `conn:charset() -> s` Get the current charset. -## `conn:charset_info() -> info_t` +### `conn:charset_info() -> info_t` Return a table of information about the current charset. -## `conn:ping() -> true | false` +### `conn:ping() -> true | false` Check if the connection to the server is still alive. -## `conn:thread_id() -> id` -## `conn:stat() -> s` -## `conn:server_info() -> s` -## `conn:host_info() -> s` -## `conn:server_version() -> n` -## `conn:proto_info() -> n` -## `conn:ssl_cipher() -> s` +### `conn:thread_id() -> id` +### `conn:stat() -> s` +### `conn:server_info() -> s` +### `conn:host_info() -> s` +### `conn:server_version() -> n` +### `conn:proto_info() -> n` +### `conn:ssl_cipher() -> s` Return various pieces of information about the connection and server. ## Transactions -## `conn:commit()` -## `conn:rollback()` +### `conn:commit()` +### `conn:rollback()` Commit/rollback the current transaction. -## `conn:set_autocommit([true | false])` +### `conn:set_autocommit([true | false])` Set autocommit on the connection (set to true if no argument is given). ## Reflection -## `conn:list_dbs([wildcard]) -> result` -## `conn:list_tables([wildcard]) -> result` -## `conn:list_processes() -> result` +### `conn:list_dbs([wildcard]) -> result` +### `conn:list_tables([wildcard]) -> result` +### `conn:list_processes() -> result` Return information about databases, tables and proceses as a stored result object that can be iterated etc. using the methods of result objects. The optional `wild` parameter may contain the wildcard characters @@ -507,29 +507,29 @@ using the methods of result objects. The optional `wild` parameter may contain t ## Remote control -## `conn:kill(pid)` +### `conn:kill(pid)` Kill a connection with a specific `pid`. -## `conn:shutdown([level])` +### `conn:shutdown([level])` Shutdown the server. `SHUTDOWN` priviledge needed. The level argument is reserved for future versions of mysql. -## `conn:refresh(options)` +### `conn:refresh(options)` Flush tables or caches, or resets replication server information. `RELOAD` priviledge needed. Options are either a table of form `{REFRESH_... = true | false, ...}` or a number of form `bit.bor(mysql.C.MYSQL_REFRESH_*, ...)` and they are as described in the [mysql manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-refresh.html). -## `conn:dump_debug_info()` +### `conn:dump_debug_info()` Instruct the server to dump debug info in the log file. `SUPER` priviledge needed. ## Client library info -## `mysql.thread_safe() -> true | false` -## `mysql.client_info() -> s` -## `mysql.client_version() -> n` +### `mysql.thread_safe() -> true | false` +### `mysql.client_info() -> s` +### `mysql.client_version() -> n` ----