1
0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00

mysql: add more documentation (#7846)

This commit is contained in:
Don Alfons Nisnoni 2021-01-09 16:40:21 +08:00 committed by GitHub
parent 256ddcee1f
commit d645e45752
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 192 additions and 173 deletions

View File

@ -13,6 +13,5 @@ fn main() {
for row in res.rows() { for row in res.rows() {
println(row.vals.join(', ')) println(row.vals.join(', '))
} }
res.free()
conn.close() conn.close()
} }

View File

@ -2,4 +2,3 @@ module mysql
#pkgconfig mysqlclient #pkgconfig mysqlclient
#include <mysql.h> # Please install the mysqlclient development headers #include <mysql.h> # Please install the mysqlclient development headers

View File

@ -1,6 +1,5 @@
module mysql module mysql
// Values for the capabilities flag bitmask used by the MySQL protocol. // Values for the capabilities flag bitmask used by the MySQL protocol.
// See more on https://dev.mysql.com/doc/dev/mysql-server/latest/group__group__cs__capabilities__flags.html#details // See more on https://dev.mysql.com/doc/dev/mysql-server/latest/group__group__cs__capabilities__flags.html#details
pub enum ConnectionFlag { pub enum ConnectionFlag {
@ -33,7 +32,7 @@ pub mut:
flag ConnectionFlag flag ConnectionFlag
} }
// connect connects to a MySQL server. // connect - create a new connection to the MySQL server.
pub fn (mut conn Connection) connect() ?bool { pub fn (mut conn Connection) connect() ?bool {
instance := C.mysql_init(conn.conn) instance := C.mysql_init(conn.conn)
conn.conn = C.mysql_real_connect(conn.conn, conn.host.str, conn.username.str, conn.password.str, conn.conn = C.mysql_real_connect(conn.conn, conn.host.str, conn.username.str, conn.password.str,
@ -44,9 +43,10 @@ pub fn (mut conn Connection) connect() ?bool {
return true return true
} }
// query executes an SQL query. // query - make an SQL query and receive the results.
// `query()` cannot be used for statements that contain binary data; you must use `real_query()` instead. // `query()` cannot be used for statements that contain binary data;
pub fn (conn Connection) query(q string) ?Result { // Use `real_query()` instead.
pub fn (mut conn Connection) query(q string) ?Result {
if C.mysql_query(conn.conn, q.str) != 0 { if C.mysql_query(conn.conn, q.str) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
@ -54,11 +54,12 @@ pub fn (conn Connection) query(q string) ?Result {
return Result{res} return Result{res}
} }
// real_query executes an SQL query. Same as `query ()`, // real_query - make an SQL query and receive the results.
// But `real_query ()` can be used for statements containing binary data. // `real_query()` can be used for statements containing binary data.
// (Binary data may contain the \0 character, which `query()` interprets as the end of the statement string). // (Binary data may contain the `\0` character, which `query()`
// In addition, `real_query()` is faster than `query()`. // interprets as the end of the statement string). In addition,
pub fn (conn Connection) real_query(q string) ?Result { // `real_query()` is faster than `query()`.
pub fn (mut conn Connection) real_query(q string) ?Result {
if C.mysql_real_query(conn.conn, q.str, q.len) != 0 { if C.mysql_real_query(conn.conn, q.str, q.len) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
@ -66,18 +67,18 @@ pub fn (conn Connection) real_query(q string) ?Result {
return Result{res} return Result{res}
} }
// select_db selects the default database for database queries. // select_db - change the default database for database queries.
pub fn (conn Connection) select_db(dbname string) ?bool { pub fn (mut conn Connection) select_db(dbname string) ?bool {
if C.mysql_select_db(conn.conn, dbname.str) != 0 { if C.mysql_select_db(conn.conn, dbname.str) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
return true return true
} }
// change_user changes the user of the specified database connection. // change_user - change the mysql user for the connection.
// if desired, the empty string value can be passed to the `dbname` parameter // Passing an empty string for the `dbname` parameter, resultsg in only changing
// resulting in only changing the user and not selecting a database. // the user and not changing the default database for the connection.
pub fn (conn Connection) change_user(username string, password string, dbname string) ?bool { pub fn (mut conn Connection) change_user(username string, password string, dbname string) ?bool {
mut ret := true mut ret := true
if dbname != '' { if dbname != '' {
ret = C.mysql_change_user(conn.conn, username.str, password.str, dbname.str) ret = C.mysql_change_user(conn.conn, username.str, password.str, dbname.str)
@ -90,20 +91,24 @@ pub fn (conn Connection) change_user(username string, password string, dbname st
return ret return ret
} }
// affected_rows returns the number of rows changed/deleted/inserted // affected_rows - return the number of rows changed/deleted/inserted
// by the last UPDATE, DELETE, or INSERT query. // by the last `UPDATE`, `DELETE`, or `INSERT` query.
pub fn (conn Connection) affected_rows() u64 { pub fn (conn &Connection) affected_rows() u64 {
return C.mysql_affected_rows(conn.conn) return C.mysql_affected_rows(conn.conn)
} }
// autocommit turns on or off auto-committing database modifications. // autocommit - turns on/off the auto-committing mode for the connection.
pub fn (conn Connection) autocommit(mode bool) { // When it is on, then each query is commited right away.
pub fn (mut conn Connection) autocommit(mode bool) {
C.mysql_autocommit(conn.conn, mode) C.mysql_autocommit(conn.conn, mode)
} }
// tables returns list of tables that match the `wildcard` parameter. // tables - returns a list of the names of the tables in the current database,
// If empty string is passed, will return all tables. // that match the simple regular expression specified by the `wildcard` parameter.
pub fn (conn Connection) tables(wildcard string) ?[]string { // The `wildcard` parameter may contain the wildcard characters `%` or `_`.
// If an empty string is passed, it will return all tables.
// Calling `tables()` is similar to executing query `SHOW TABLES [LIKE wildcard]`.
pub fn (conn &Connection) tables(wildcard string) ?[]string {
cres := C.mysql_list_tables(conn.conn, wildcard.str) cres := C.mysql_list_tables(conn.conn, wildcard.str)
if isnil(cres) { if isnil(cres) {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@ -113,27 +118,28 @@ pub fn (conn Connection) tables(wildcard string) ?[]string {
for row in res.rows() { for row in res.rows() {
tables << row.vals[0] tables << row.vals[0]
} }
res.free()
return tables return tables
} }
// escape_string creates a legal SQL string for use in an SQL statement. // escape_string - creates a legal SQL string for use in an SQL statement.
pub fn (conn Connection) escape_string(s string) string { // The `s` argument is encoded to produce an escaped SQL string,
// taking into account the current character set of the connection.
pub fn (conn &Connection) escape_string(s string) string {
to := malloc(2 * s.len + 1) to := malloc(2 * s.len + 1)
C.mysql_real_escape_string_quote(conn.conn, to, s.str, s.len, `\'`) C.mysql_real_escape_string_quote(conn.conn, to, s.str, s.len, `\'`)
return unsafe {to.vstring()} return unsafe { to.vstring() }
} }
// set_option is used to set extra connect options and affect behavior for a connection. // set_option - sets extra connect options that affect the behavior of
// This function may be called multiple times to set several options. // a connection. This function may be called multiple times to set several
// To retrieve option values, use `get_option()`. // options. To retrieve the current values for an option, use `get_option()`.
pub fn (conn Connection) set_option(option_type int, val voidptr) { pub fn (mut conn Connection) set_option(option_type int, val voidptr) {
C.mysql_options(conn.conn, option_type, val) C.mysql_options(conn.conn, option_type, val)
} }
// get_option returns the current value of an option settable `set_option`. // get_option - return the value of an option, settable by `set_option`.
// The value should be treated as read only. // https://dev.mysql.com/doc/c-api/5.7/en/mysql-get-option.html
pub fn (conn Connection) get_option(option_type int) ?voidptr { pub fn (conn &Connection) get_option(option_type int) ?voidptr {
ret := voidptr(0) ret := voidptr(0)
if C.mysql_get_option(conn.conn, option_type, &ret) != 0 { if C.mysql_get_option(conn.conn, option_type, &ret) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@ -141,79 +147,86 @@ pub fn (conn Connection) get_option(option_type int) ?voidptr {
return ret return ret
} }
// refresh flushes tables or caches, or resets replication server information. // refresh - flush the tables or caches, or resets replication server
// The connected user must have the `RELOAD` privilege. // information. The connected user must have the `RELOAD` privilege.
pub fn (conn Connection) refresh(options u32) ?bool { pub fn (mut conn Connection) refresh(options u32) ?bool {
if C.mysql_refresh(conn.conn, options) != 0 { if C.mysql_refresh(conn.conn, options) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
return true return true
} }
// reset resets the connection to clear the session state. // reset - resets the connection, and clear the session state.
pub fn (conn Connection) reset() ?bool { pub fn (mut conn Connection) reset() ?bool {
if C.mysql_reset_connection(conn.conn) != 0 { if C.mysql_reset_connection(conn.conn) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
return true return true
} }
// ping pings a server connection, or tries to reconnect if the connection has gone down. // ping - pings a server connection, or tries to reconnect if the connection
pub fn (conn Connection) ping() ?bool { // has gone down.
pub fn (mut conn Connection) ping() ?bool {
if C.mysql_ping(conn.conn) != 0 { if C.mysql_ping(conn.conn) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
return true return true
} }
// close closes a previously opened database connection. // close - closes the connection.
pub fn (conn &Connection) close() { pub fn (mut conn Connection) close() {
C.mysql_close(conn.conn) C.mysql_close(conn.conn)
} }
// -------------------------- MYSQL INFO & VERSION -------------------------- // info - returns information about the most recently executed query.
// info returns information about the most recently executed query. // See more on https://dev.mysql.com/doc/c-api/8.0/en/mysql-info.html
pub fn (conn Connection) info() string { pub fn (conn &Connection) info() string {
return resolve_nil_str(C.mysql_info(conn.conn)) return resolve_nil_str(C.mysql_info(conn.conn))
} }
// get_host_info returns a string describing the connection. // get_host_info - returns a string describing the type of connection in use,
pub fn (conn Connection) get_host_info() string { // including the server host name.
return unsafe {C.mysql_get_host_info(conn.conn).vstring()} pub fn (conn &Connection) get_host_info() string {
return unsafe { C.mysql_get_host_info(conn.conn).vstring() }
} }
// get_server_info returns the server version number as a string. // get_server_info - returns a string representing the MySQL server version.
pub fn (conn Connection) get_server_info() string { // For example, `8.0.24`.
return unsafe {C.mysql_get_server_info(conn.conn).vstring()} pub fn (conn &Connection) get_server_info() string {
return unsafe { C.mysql_get_server_info(conn.conn).vstring() }
} }
// get_server_version returns the server version number as an integer. // get_server_version - returns an integer, representing the MySQL server
pub fn (conn Connection) get_server_version() u64 { // version. The value has the format `XYYZZ` where `X` is the major version,
// `YY` is the release level (or minor version), and `ZZ` is the sub-version
// within the release level. For example, `8.0.24` is returned as `80024`.
pub fn (conn &Connection) get_server_version() u64 {
return C.mysql_get_server_version(conn.conn) return C.mysql_get_server_version(conn.conn)
} }
// --------------------------------- CLIENT --------------------------------- // dump_debug_info - instructs the server to write debugging information
// get_client_info returns client version information as a string. // to the error log. The connected user must have the `SUPER` privilege.
pub fn get_client_info() string { pub fn (mut conn Connection) dump_debug_info() ?bool {
return unsafe {C.mysql_get_client_info().vstring()}
}
// get_client_version returns client version information as an integer.
pub fn get_client_version() u64 {
return C.mysql_get_client_version()
}
// ------------------------------- MYSQL DEBUG ------------------------------
// dump_debug_info causes the server to write debug information to the log
pub fn (conn Connection) dump_debug_info() ?bool {
if C.mysql_dump_debug_info(conn.conn) != 0 { if C.mysql_dump_debug_info(conn.conn) != 0 {
return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
} }
return true return true
} }
// debug does a `DBUG_PUSH` with the given string. // get_client_info - returns client version information as a string.
// See https://dev.mysql.com/doc/refman/5.7/en/mysql-debug.html pub fn get_client_info() string {
return unsafe { C.mysql_get_client_info().vstring() }
}
// get_client_version - returns the client version information as an integer.
pub fn get_client_version() u64 {
return C.mysql_get_client_version()
}
// debug - does a `DBUG_PUSH` with the given string.
// `debug()` uses the Fred Fish debug library.
// To use this function, you must compile the client library to support debugging.
// See https://dev.mysql.com/doc/c-api/8.0/en/mysql-debug.html
pub fn debug(debug string) { pub fn debug(debug string) {
C.mysql_debug(debug.str) C.mysql_debug(debug.str)
} }

View File

@ -9,86 +9,6 @@ pub mut:
vals []string vals []string
} }
// fetch_row fetches the next row from the result set.
pub fn (r Result) fetch_row() &byteptr {
return C.mysql_fetch_row(r.result)
}
// n_rows returns the number of rows in the result set.
pub fn (r Result) n_rows() u64 {
return C.mysql_num_rows(r.result)
}
// n_fields returns the number of columns in a result set.
pub fn (r Result) n_fields() int {
return C.mysql_num_fields(r.result)
}
// rows returns rows with `array` of columns.
pub fn (r Result) rows() []Row {
mut rows := []Row{}
nr_cols := r.n_fields()
for rr := r.fetch_row(); rr; rr = r.fetch_row() {
mut row := Row{}
for i in 0 .. nr_cols {
if unsafe {rr[i] == 0} {
row.vals << ''
} else {
row.vals << mystring(unsafe {byteptr(rr[i])})
}
}
rows << row
}
return rows
}
// Returns rows with `map` of columns instead `array` of columns.
pub fn (r Result) maps() []map[string]string {
mut array_map := []map[string]string{}
rows := r.rows()
fields := r.fields()
for i in 0 .. rows.len {
mut map_val := map[string]string{}
for j in 0 .. fields.len {
map_val[fields[j].name] = rows[i].vals[j]
}
array_map << map_val
}
return array_map
}
// fields returns an array of all field structures.
pub fn (r Result) fields() []Field {
mut fields := []Field{}
nr_cols := r.n_fields()
orig_fields := C.mysql_fetch_fields(r.result)
for i in 0 .. nr_cols {
unsafe {fields << Field{
name: mystring(orig_fields[i].name)
org_name: mystring(orig_fields[i].org_name)
table: mystring(orig_fields[i].table)
org_table: mystring(orig_fields[i].org_table)
db: mystring(orig_fields[i].db)
catalog: mystring(orig_fields[i].catalog)
def: resolve_nil_str(orig_fields[i].def)
length: orig_fields.length
max_length: orig_fields.max_length
name_length: orig_fields.name_length
org_name_length: orig_fields.org_name_length
table_length: orig_fields.table_length
org_table_length: orig_fields.org_table_length
db_length: orig_fields.db_length
catalog_length: orig_fields.catalog_length
def_length: orig_fields.def_length
flags: orig_fields.flags
decimals: orig_fields.decimals
charsetnr: orig_fields.charsetnr
type_: FieldType(orig_fields.@type)
}}
}
return fields
}
pub struct Field { pub struct Field {
name string name string
org_name string org_name string
@ -112,6 +32,93 @@ pub struct Field {
type_ FieldType type_ FieldType
} }
// fetch_row - fetches the next row from a result.
pub fn (r Result) fetch_row() &byteptr {
return C.mysql_fetch_row(r.result)
}
// n_rows - returns the number of rows from a result.
pub fn (r Result) n_rows() u64 {
return C.mysql_num_rows(r.result)
}
// n_fields - returns the number of columns from a result.
pub fn (r Result) n_fields() int {
return C.mysql_num_fields(r.result)
}
// rows - returns array of rows, each containing an array of values,
// one for each column.
pub fn (r Result) rows() []Row {
mut rows := []Row{}
nr_cols := r.n_fields()
for rr := r.fetch_row(); rr; rr = r.fetch_row() {
mut row := Row{}
for i in 0 .. nr_cols {
if unsafe { rr[i] == 0 } {
row.vals << ''
} else {
row.vals << mystring(unsafe { byteptr(rr[i]) })
}
}
rows << row
}
return rows
}
// maps - returns an array of maps, each containing a set of
// field name: field value pairs.
pub fn (r Result) maps() []map[string]string {
mut array_map := []map[string]string{}
rows := r.rows()
fields := r.fields()
for i in 0 .. rows.len {
mut map_val := map[string]string{}
for j in 0 .. fields.len {
map_val[fields[j].name] = rows[i].vals[j]
}
array_map << map_val
}
return array_map
}
// fields - returns an array of fields/columns.
// The definitions apply primarily for columns of results,
// such as those produced by `SELECT` statements.
pub fn (r Result) fields() []Field {
mut fields := []Field{}
nr_cols := r.n_fields()
orig_fields := C.mysql_fetch_fields(r.result)
for i in 0 .. nr_cols {
unsafe {
fields << Field{
name: mystring(orig_fields[i].name)
org_name: mystring(orig_fields[i].org_name)
table: mystring(orig_fields[i].table)
org_table: mystring(orig_fields[i].org_table)
db: mystring(orig_fields[i].db)
catalog: mystring(orig_fields[i].catalog)
def: resolve_nil_str(orig_fields[i].def)
length: orig_fields.length
max_length: orig_fields.max_length
name_length: orig_fields.name_length
org_name_length: orig_fields.org_name_length
table_length: orig_fields.table_length
org_table_length: orig_fields.org_table_length
db_length: orig_fields.db_length
catalog_length: orig_fields.catalog_length
def_length: orig_fields.def_length
flags: orig_fields.flags
decimals: orig_fields.decimals
charsetnr: orig_fields.charsetnr
type_: FieldType(orig_fields.@type)
}
}
}
return fields
}
// str - serializes the field
pub fn (f Field) str() string { pub fn (f Field) str() string {
return ' return '
{ {
@ -139,7 +146,8 @@ pub fn (f Field) str() string {
' '
} }
// free frees memory used by a result set // free - frees the memory used by a result
pub fn (r Result) free() { [unsafe]
pub fn (r &Result) free() {
C.mysql_free_result(r.result) C.mysql_free_result(r.result)
} }

View File

@ -1,21 +1,21 @@
module mysql module mysql
// get_error_msg returns error message from MySQL instance. // get_error_msg - returns error message from MySQL instance.
fn get_error_msg(conn &C.MYSQL) string { fn get_error_msg(conn &C.MYSQL) string {
return unsafe {C.mysql_error(conn).vstring()} return unsafe { C.mysql_error(conn).vstring() }
} }
// get_errno returns error number from MySQL instance. // get_errno - returns error number from MySQL instance.
fn get_errno(conn &C.MYSQL) int { fn get_errno(conn &C.MYSQL) int {
return C.mysql_errno(conn) return C.mysql_errno(conn)
} }
// resolve_nil_str returns empty string if passed value is a nil pointer. // resolve_nil_str - returns an empty string if passed value is a nil pointer.
fn resolve_nil_str(ptr byteptr) string { fn resolve_nil_str(ptr byteptr) string {
if isnil(ptr) { if isnil(ptr) {
return '' return ''
} }
return unsafe {ptr.vstring()} return unsafe { ptr.vstring() }
} }
[inline] [inline]