From 39c5c9b966bf56092b1a673ba5971743d342da73 Mon Sep 17 00:00:00 2001 From: Don Alfons Nisnoni Date: Thu, 11 Jun 2020 16:07:17 +0800 Subject: [PATCH] mysql: update documentation --- vlib/mysql/_cdefs.c.v | 1 + vlib/mysql/mysql.v | 73 +++++++++++++++++++++++++------------------ vlib/mysql/result.v | 26 +++++++-------- vlib/mysql/utils.v | 7 +++-- 4 files changed, 61 insertions(+), 46 deletions(-) diff --git a/vlib/mysql/_cdefs.c.v b/vlib/mysql/_cdefs.c.v index ceefcbed85..1583a4f9e2 100644 --- a/vlib/mysql/_cdefs.c.v +++ b/vlib/mysql/_cdefs.c.v @@ -28,6 +28,7 @@ struct C.MYSQL_FIELD { fn C.mysql_init(mysql &C.MYSQL) &C.MYSQL fn C.mysql_real_connect(mysql &C.MYSQL, host byteptr, user byteptr, passwd byteptr, db byteptr, port u32, unix_socket byteptr, clientflag u64) &C.MYSQL fn C.mysql_query(mysql &C.MYSQL, q byteptr) int +fn C.mysql_real_query(mysql &C.MYSQL, q byteptr, len u32) int fn C.mysql_select_db(mysql &C.MYSQL, db byteptr) int fn C.mysql_change_user(mysql &C.MYSQL, user byteptr, password byteptr, db byteptr) bool fn C.mysql_affected_rows(mysql &C.MYSQL) u64 diff --git a/vlib/mysql/mysql.v b/vlib/mysql/mysql.v index 9e1c46b216..2ea913f584 100644 --- a/vlib/mysql/mysql.v +++ b/vlib/mysql/mysql.v @@ -17,7 +17,7 @@ pub mut: flag int } -// connect Connects to a MySQL server +// connect connects to a MySQL server. pub fn (mut conn Connection) connect() ?bool { instance := C.mysql_init(conn.conn) conn.conn = C.mysql_real_connect( @@ -36,7 +36,8 @@ pub fn (mut conn Connection) connect() ?bool { return true } -// query Performs a query on the database +// query executes an SQL query. +// `query()` cannot be used for statements that contain binary data; you must use `real_query()` instead. pub fn (conn Connection) query(q string) ?Result { if C.mysql_query(conn.conn, q.str) != 0 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) @@ -45,7 +46,19 @@ pub fn (conn Connection) query(q string) ?Result { return Result{res} } -// select_db Selects the default database for database queries +// real_query executes an SQL query. Same as `query ()`, +// But `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). +// In addition, `real_query()` is faster than `query()`. +pub fn (conn Connection) real_query(q string) ?Result { + 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)) + } + res := C.mysql_store_result(conn.conn) + return Result{res} +} + +// select_db selects the default database for database queries. pub fn (conn Connection) select_db(dbname string) ?bool { if C.mysql_select_db(conn.conn, dbname.str) != 0 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) @@ -53,9 +66,9 @@ pub fn (conn Connection) select_db(dbname string) ?bool { return true } -// change_user Changes the user of the specified database connection. -// If desired, the empty string value can be passed to the `dbname` parameter -// resulting in only changing the user and not selecting a database +// change_user changes the user of the specified database connection. +// if desired, the empty string value can be passed to the `dbname` parameter +// resulting in only changing the user and not selecting a database. pub fn (conn Connection) change_user(username, password, dbname string) ?bool { mut ret := true if dbname != '' { @@ -69,19 +82,19 @@ pub fn (conn Connection) change_user(username, password, dbname string) ?bool { return ret } -// affected_rows Returns the number of rows changed/deleted/inserted -// by the last UPDATE, DELETE, or INSERT query +// affected_rows returns the number of rows changed/deleted/inserted +// by the last UPDATE, DELETE, or INSERT query. pub fn (conn Connection) affected_rows() u64 { return C.mysql_affected_rows(conn.conn) } -// autocommit Turns on or off auto-committing database modifications +// autocommit turns on or off auto-committing database modifications. pub fn (conn Connection) autocommit(mode bool) { C.mysql_autocommit(conn.conn, mode) } -// tables Returns list of tables that match the `wildcard` parameter. -// If empty string is passed, will return all tables +// tables returns list of tables that match the `wildcard` parameter. +// If empty string is passed, will return all tables. pub fn (conn Connection) tables(wildcard string) ?[]string { cres := C.mysql_list_tables(conn.conn, wildcard.str) if isnil(cres) { @@ -96,7 +109,7 @@ pub fn (conn Connection) tables(wildcard string) ?[]string { 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 { len := C.strlen(s.str) to := malloc(2 * len + 1) @@ -106,15 +119,15 @@ pub fn (conn Connection) escape_string(s string) string { return string(to) } -// set_option Can be used to set extra connect options and affect behavior for a connection. +// set_option is used to set extra connect options and affect behavior for a connection. // This function may be called multiple times to set several options. -// To retrieve option values, use `get_option()` +// To retrieve option values, use `get_option()`. pub fn (conn Connection) set_option(option_type int, val voidptr) { C.mysql_options(conn.conn, option_type, val) } -// get_option Returns the current value of an option settable `set_option`. -// The value should be treated as read only +// get_option returns the current value of an option settable `set_option`. +// The value should be treated as read only. pub fn (conn Connection) get_option(option_type int) ?voidptr { ret := voidptr(0) if C.mysql_get_option(conn.conn, option_type, &ret) != 0 { @@ -123,8 +136,8 @@ pub fn (conn Connection) get_option(option_type int) ?voidptr { return ret } -// refresh Flushes tables or caches, or resets replication server information. -// The connected user must have the `RELOAD` privilege +// refresh flushes tables or caches, or resets replication server information. +// The connected user must have the `RELOAD` privilege. pub fn (conn Connection) refresh(options u32) ?bool { if C.mysql_refresh(conn.conn, options) != 0 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) @@ -132,15 +145,15 @@ pub fn (conn Connection) refresh(options u32) ?bool { return true } -// reset_connection Resets the connection to clear the session state -pub fn (conn Connection) reset_connection() ?bool { +// reset resets the connection to clear the session state. +pub fn (conn Connection) reset() ?bool { if C.mysql_reset_connection(conn.conn) != 0 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) } 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 has gone down. pub fn (conn Connection) ping() ?bool { if C.mysql_ping(conn.conn) != 0 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) @@ -148,48 +161,48 @@ pub fn (conn Connection) ping() ?bool { return true } -// close Closes a previously opened database connection +// close closes a previously opened database connection. pub fn (conn &Connection) close() { 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. pub fn (conn Connection) info() string { 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 connection. pub fn (conn Connection) get_host_info() string { return string(C.mysql_get_host_info(conn.conn)) } -// get_server_info Returns the server version number as a string +// get_server_info returns the server version number as a string. pub fn (conn Connection) get_server_info() string { return string(C.mysql_get_server_info(conn.conn)) } -// get_server_version Returns the server version number as an integer +// get_server_version returns the server version number as an integer. pub fn (conn Connection) get_server_version() u64 { return C.mysql_get_server_version(conn.conn) } /* --------------------------------- CLIENT --------------------------------- */ -// get_client_info Returns client version information as a string +// get_client_info returns client version information as a string. pub fn get_client_info() string { return string(C.mysql_get_client_info()) } -// get_client_version Returns client version information as an integer +// 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 +// 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 { return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn)) @@ -197,7 +210,7 @@ pub fn (conn Connection) dump_debug_info() ?bool { return true } -// debug Does a `DBUG_PUSH` with the given string. +// debug does a `DBUG_PUSH` with the given string. // See https://dev.mysql.com/doc/refman/5.7/en/mysql-debug.html pub fn debug(debug string) { C.mysql_debug(debug.str) diff --git a/vlib/mysql/result.v b/vlib/mysql/result.v index 7a7ff82c79..1cdf0643c5 100644 --- a/vlib/mysql/result.v +++ b/vlib/mysql/result.v @@ -9,25 +9,25 @@ pub mut: vals []string } -// Fetches the next row from the result set +// fetch_row fetches the next row from the result set. pub fn (r Result) fetch_row() &byteptr { return C.mysql_fetch_row(r.result) } -// num_rows Returns the number of rows in the result set -pub fn (r Result) num_rows() u64 { +// 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) } -// num_fields Returns the number of columns in a result set -pub fn (r Result) num_fields() int { +// 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 +// rows returns rows with `array` of columns. pub fn (r Result) rows() []Row { mut rows := []Row{} - nr_cols := r.num_fields() + nr_cols := r.n_fields() for rr := r.fetch_row(); rr; rr = r.fetch_row() { mut row := Row{} for i in 0..nr_cols { @@ -42,11 +42,11 @@ pub fn (r Result) rows() []Row { return rows } -// maps Returns rows with `map` of columns instead `array` of columns +// 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.fetch_fields() + fields := r.fields() for i in 0..rows.len { mut map_val := map[string]string for j in 0..fields.len { @@ -57,10 +57,10 @@ pub fn (r Result) maps() []map[string]string { return array_map } -// fetch_fields Returns an array of all field structures -pub fn (r Result) fetch_fields() []Field { +// fields returns an array of all field structures. +pub fn (r Result) fields() []Field { mut fields := []Field{} - nr_cols := r.num_fields() + nr_cols := r.n_fields() orig_fields := C.mysql_fetch_fields(r.result) for i in 0..nr_cols { fields << Field{ @@ -139,7 +139,7 @@ pub fn (f Field) str() string { ' } -// free Frees memory used by a result set +// free frees memory used by a result set pub fn (r Result) free() { C.mysql_free_result(r.result) } diff --git a/vlib/mysql/utils.v b/vlib/mysql/utils.v index f207110e46..647c2c9718 100644 --- a/vlib/mysql/utils.v +++ b/vlib/mysql/utils.v @@ -1,16 +1,17 @@ module mysql +// get_error_msg returns error message from MySQL instance. fn get_error_msg(conn &C.MYSQL) string { return string(C.mysql_error(conn)) } +// get_errno returns error number from MySQL instance. fn get_errno(conn &C.MYSQL) int { return C.mysql_errno(conn) } +// resolve_nil_str returns empty string if passed value is a nil pointer. fn resolve_nil_str(ptr byteptr) string { - if isnil(ptr) { - return '' - } + if isnil(ptr) { return '' } return string(ptr) }