Connect to a mysql server, optionally selecting a working database and charset.
In the second form, `options_t` is a table that besides `host`, `user`, `pass`, `db`, `charset`, `port` can have the following fields:
*`unix_socket`: specify a unix socket filename to connect to
*`flags`: bit field corresponding to mysql [client_flag](http://dev.mysql.com/doc/refman/5.7/en/mysql-real-connect.html) parameter
* can be a table of form `{CLIENT_... = true | false, ...}`, or
* a number of form `bit.bor(mysql.C.CLIENT_..., ...)`
*`options`: a table of form `{MYSQL_OPT_... = value, ...}`, containing options per [mysql_options()](http://dev.mysql.com/doc/refman/5.7/en/mysql-options.html) (values are properly converted from Lua types)
*`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()`
Close a mysql connection freeing all associated resources (otherwise called when `conn` is garbage collected).
# Queries
## `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`
Escape a value to be safely embedded in SQL queries. Assumes the current charset.
# Fetching results
## `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`
Return a result object that will fetch the rows in the current result set from the server on demand.
Fetch and return the next row of values from the current result set. Returns nil if there are no more rows to fetch.
* the `mode` arg can contain any combination of the following letters:
*`"n"` - return values in a table with numeric indices as keys.
*`"a"` - return values in a table with field names as keys.
*`"s"` - do not convert numeric and time values to Lua types.
* the `row_t` arg is an optional table to store the row values in, instead of creating a new one on each fetch.
* options "a" and "n" can be combined to get a table with both numeric and field name indices.
* if `mode` is missing or if neither "a" nor "n" is specified, the values are returned to the caller unpacked, after a first value that is always true, to make it easy to distinguish between a valid `NULL` value in the first column and eof.
* in "n" mode, the result table may contain `nil` values so `#row_t` and `ipairs(row_t)` are out; instead iterate from 1 to `result:field_count()`.
* in "a" mode, for fields with duplicate names only the last field will be present.
* if `mode` does not specify `"s"`, the following conversions are applied on the returned values:
* integer types are returned as Lua numbers, except bigint which is returned as an `int64_t` cdata (or `uint64` if unsigned).
* date/time types are returned as tables in the usual `os.date"*t"` format (date fields are missing for time-only types and viceversa).
* decimal/numeric types are returned as Lua strings.
* 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.
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()`
Free the result buffer (otherwise called when `result` is garbage collected).
## `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`
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)`
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`
Return various pieces of information about the previously executed query.
Return information about the fields (columns) in the current result set.
# Result bookmarks
## `result:tell() -> bookmark`
Get a bookmark to the current row to be later seeked into with `seek()`.
## `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`
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`
Check if there are more result sets after this one.
# Prepared statements
Prepared statements are a way to run queries and retrieve results more efficiently from the database, in particular:
* parametrized queries allow sending query parameters in their native format, avoiding having to convert values into strings and escaping those strings.
* running the same query multiple times with different parameters each time allows the server to reuse the parsed query and possibly the query plan between runs.
* fetching the result rows in preallocated buffers avoids dynamic allocation on each row fetch.
The flow for prepared statements is like this:
* call `conn:prepare()` to prepare a query and get a statement object.
* call `stmt:bind_params()` and `stmt:bind_result()` to get the buffer objects for setting params and getting row values.
* run the query multiple times; each time:
* call `params:set()` for each param to set param values.
* call `stmt:exec()` to run the query.
* fetch the resulting rows one by one; for each row:
* call `stmt:fetch()` to get the next row (it returns false if it was the last row).
* 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`
Prepare a query for multiple execution and return a statement object.
## `stmt:exec()`
Execute a prepared statement.
## `stmt:store_result()`
Fetch all the rows in the current result set from the server, otherwise the rows are fetched on demand.
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()`
Free the current result and all associated resources (otherwise the result is closed when the statement is closed).
## `stmt:close()`
Close a prepared statement and free all associated resources (otherwise the statement is closed when garbage collected).
## `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`
Return various pieces of information on the executed statement.
## `stmt:reset()`
See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-reset.html).
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.
The types must be valid, fully specified SQL types, eg.
*`smallint unsigned` specifies a 16bit unsigned integer
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. If no types are specified, appropriate type definitions will be created automatically as to minimize type conversions. Variable-sized fields will get a buffer sized according to data type's maximum allowed size and `maxsize` (which defaults to 64k).
See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-attr-set.html) for these.
# Connection info
## `conn:set_charset(charset)`
Change the current charset.
## `conn:select_db(dbname)`
Change the current database.
## `conn:change_user(user, [pass], [db])`
Change the current user and optionally select a database.
## `conn:set_multiple_statements(true | false)`
Enable or disable support for query strings containing multiple statements separated by a semi-colon.
## `conn:charset() -> s`
Get the current charset.
## `conn:charset_info() -> info_t`
Return a table of information about the current charset.
## `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`
Return various pieces of information about the connection and server.
# Transactions
## `conn:commit()`
## `conn:rollback()`
Commit/rollback the current transaction.
## `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`
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 `"%"` or `"_"`, similar to executing the query `SHOW DATABASES [LIKE wild]`.
# Remote control
## `conn:kill(pid)`
Kill a connection with a specific `pid`.
## `conn:shutdown([level])`
Shutdown the server. `SHUTDOWN` priviledge needed. The level argument is reserved for future versions of mysql.
## `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()`
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`
----
## TODO
* reader function for getting large blobs in chunks using mysql_stmt_fetch_column: `stmt:chunks(i[, bufsize])` or `stmt:read()` ?
* test with Linux, OSX, 64bit OSs
* support connecting against different runtimes (client_library option)