sys4/mysql
1
0
Fork 0
mirror of https://github.com/luapower/mysql.git synced 2024-12-28 20:00:33 +01:00
Code Issues Releases Wiki Activity

unimportant

Browse Source
This commit is contained in:
Cosmin Apreuetsei 2014-01-21 21:59:43 +02:00
parent 9474be1da2
commit d24dea3093
1 changed files with 54 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
mysql.md
View File

@ -7,7 +7,7 @@ tagline: mysql database client
A complete, lightweight ffi binding of the mysql client library. A complete, lightweight ffi binding of the mysql client library.
## Summary ## Summary
-------------------------------------------------------------------------------- -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- --------------------------------------------------------------------------------
**[Connections]** **[Connections]**
@ -122,7 +122,7 @@ A complete, lightweight ffi binding of the mysql client library.
`mysql.client_version() -> n` `mysql.client_version() -> n`
-------------------------------------------------------------------------------- -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- --------------------------------------------------------------------------------
## Features: ## Features
* covers all of the functionality provided by the mysql C API * covers all of the functionality provided by the mysql C API
* all data types are supported with options for conversion * all data types are supported with options for conversion
@ -132,7 +132,7 @@ A complete, lightweight ffi binding of the mysql client library.
* lightweight OOP-style API using only `ffi.metatype` * lightweight OOP-style API using only `ffi.metatype`
* no external dependencies * no external dependencies
## Example: ## Example
~~~{.lua} ~~~{.lua}
function print_help(search) function print_help(search)
@ -165,14 +165,16 @@ end
print_help'CONCAT%' print_help'CONCAT%'
~~~ ~~~
# Connections ## Connections
## `mysql.connect(host, [user], [pass], [db], [charset], [port]) -> conn` ## `mysql.connect(host, [user], [pass], [db], [charset], [port]) -> conn`
## `mysql.connect(options_t) -> conn` ## `mysql.connect(options_t) -> conn`
Connect to a mysql server, optionally selecting a working database and charset. 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: 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 * `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 * `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 * can be a table of form `{CLIENT_... = true | false, ...}`, or
@ -185,17 +187,18 @@ In the second form, `options_t` is a table that besides `host`, `user`, `pass`,
Close a mysql connection freeing all associated resources (otherwise called when `conn` is garbage collected). Close a mysql connection freeing all associated resources (otherwise called when `conn` is garbage collected).
# Queries ## 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). 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. Escape a value to be safely embedded in SQL queries. Assumes the current charset.
# Fetching results ## Fetching results
## `conn:store_result() -> result` ## `conn:store_result() -> result`
@ -208,6 +211,7 @@ Return a result object that will fetch the rows in the current result set from t
## `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. 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: * the `mode` arg can contain any combination of the following letters:
* `"n"` - return values in a table with numeric indices as keys. * `"n"` - return values in a table with numeric indices as keys.
* `"a"` - return values in a table with field names as keys. * `"a"` - return values in a table with field names as keys.
@ -227,7 +231,8 @@ Fetch and return the next row of values from the current result set. Returns nil
## `result:rows([mode[, row_t]]) -> iterator() -> row_num, val1, val2, ...` ## `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, 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. 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()`
@ -235,17 +240,19 @@ 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. 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. 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. Seek back to a particular row number to refetch the rows from there.
# Query info ## Query info
## `conn:field_count() -> n` ## `conn:field_count() -> n`
## `conn:affected_rows() -> n` ## `conn:affected_rows() -> n`
@ -257,7 +264,7 @@ Seek back to a particular row number to refetch the rows from there.
Return various pieces of information about the previously executed query. Return various pieces of information about the previously executed query.
# Field info ## Field info
## `result:field_count() -> n` ## `result:field_count() -> n`
## `result:field_name(field_number) -> s` ## `result:field_name(field_number) -> s`
@ -267,7 +274,7 @@ Return various pieces of information about the previously executed query.
Return information about the fields (columns) in the current result set. Return information about the fields (columns) in the current result set.
# Result bookmarks ## Result bookmarks
## `result:tell() -> bookmark` ## `result:tell() -> bookmark`
@ -277,24 +284,27 @@ Get a bookmark to the current row to be later seeked into with `seek()`.
Seek to a previous saved row bookmark, or to a specific row number, fetching more rows as needed. Seek to a previous saved row bookmark, or to a specific row number, fetching more rows as needed.
# Multiple statement queries ## 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. 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. Check if there are more result sets after this one.
# Prepared statements ## Prepared statements
Prepared statements are a way to run queries and retrieve results more efficiently from the database, in particular: 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. * 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. * 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. * fetching the result rows in preallocated buffers avoids dynamic allocation on each row fetch.
The flow for prepared statements is like this: The flow for prepared statements is like this:
* call `conn:prepare()` to prepare a query and get a statement object. * 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. * 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: * run the query multiple times; each time:
@ -319,7 +329,9 @@ Fetch all the rows in the current result set from the server, otherwise the rows
## `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. 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()`
@ -354,13 +366,15 @@ See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-reset.html).
Seek into the current result set. Seek into the current result set.
# Prepared statements I/O ## 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. 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. The types must be valid, fully specified SQL types, eg.
* `smallint unsigned` specifies a 16bit unsigned integer * `smallint unsigned` specifies a 16bit unsigned integer
* `bit(32)` specifies a 32bit bit field * `bit(32)` specifies a 32bit bit field
* `varchar(200)` specifies a 200 byte varchar. * `varchar(200)` specifies a 200 byte varchar.
@ -372,6 +386,7 @@ The types must be valid, fully specified SQL types, eg.
## `params:set_date(i, [year], [month], [day], [hour], [min], [sec], [frac])` ## `params:set_date(i, [year], [month], [day], [hour], [min], [sec], [frac])`
Set a parameter value. Set a parameter value.
* the first form is for setting integers and bit fields. * the first form is for setting integers and bit fields.
* the second and third forms are for setting variable-sized fields and decimal/numeric fields. * the second and third forms are for setting variable-sized fields and decimal/numeric fields.
* the last forms are for setting date/time/datetime/timestamp fields. * the last forms are for setting date/time/datetime/timestamp fields.
@ -383,7 +398,11 @@ 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. 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). 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).
## `fields:get(i) -> value` ## `fields:get(i) -> value`
## `fields:get_datetime(i) -> year, month, day, hour, min, sec, frac` ## `fields:get_datetime(i) -> year, month, day, hour, min, sec, frac`
@ -398,11 +417,11 @@ Check if a value is null without having to get it if it's not.
Check if a value was truncated due to insufficient buffer space. 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. Return the list of type definitions that describe the result of a prepared statement.
# Prepared statements settings ## Prepared statements settings
## `stmt:update_max_length() -> true | false` ## `stmt:update_max_length() -> true | false`
## `stmt:set_update_max_length(true | false)` ## `stmt:set_update_max_length(true | false)`
@ -414,7 +433,7 @@ Return the list of type definitions that describe the result of a prepared state
See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-attr-set.html) for these. See [manual](http://dev.mysql.com/doc/refman/5.7/en/mysql-stmt-attr-set.html) for these.
# Connection info ## Connection info
## `conn:set_charset(charset)` ## `conn:set_charset(charset)`
@ -454,7 +473,7 @@ Check if the connection to the server is still alive.
Return various pieces of information about the connection and server. Return various pieces of information about the connection and server.
# Transactions ## Transactions
## `conn:commit()` ## `conn:commit()`
## `conn:rollback()` ## `conn:rollback()`
@ -465,15 +484,17 @@ Commit/rollback the current transaction.
Set autocommit on the connection (set to true if no argument is given). Set autocommit on the connection (set to true if no argument is given).
# Reflection ## Reflection
## `conn:list_dbs([wildcard]) -> result` ## `conn:list_dbs([wildcard]) -> result`
## `conn:list_tables([wildcard]) -> result` ## `conn:list_tables([wildcard]) -> result`
## `conn:list_processes() -> 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]`. 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 ## Remote control
## `conn:kill(pid)` ## `conn:kill(pid)`
@ -485,13 +506,15 @@ Shutdown the server. `SHUTDOWN` priviledge needed. The level argument is reserve
## `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). 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. Instruct the server to dump debug info in the log file. `SUPER` priviledge needed.
# Client library info ## Client library info
## `mysql.thread_safe() -> true | false` ## `mysql.thread_safe() -> true | false`
## `mysql.client_info() -> s` ## `mysql.client_info() -> s`
@ -499,7 +522,7 @@ Instruct the server to dump debug info in the log file. `SUPER` priviledge neede
---- ----
## TODO ## TODO
* reader function for getting large blobs in chunks using mysql_stmt_fetch_column: `stmt:chunks(i[, bufsize])` or `stmt:read()` ? * 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 * test with Linux, OSX, 64bit OSs