mysql: add more documentation (#7846)

examples/database/mysql.v

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

vlib/mysql/_cdefs_nix.c.v

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

vlib/mysql/mysql.v

@@ -1,6 +1,5 @@
 module mysql
 
-
 // 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
 pub enum ConnectionFlag {
@@ -33,7 +32,7 @@ pub mut:
 	flag     ConnectionFlag
 }
 
-// connect connects to a MySQL server.
+// connect - create a new connection to the MySQL server.
 pub fn (mut conn Connection) connect() ?bool {
 	instance := C.mysql_init(conn.conn)
 	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
 }
 
-// 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 {
 		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}
 }
 
-// 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 {
 		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}
 }
 
-// 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 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
 	}
 	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
 	if dbname != '' {
 		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
 }
 
-// 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)
 }
 
-// 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)
 }
 
-// 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)
 	if isnil(cres) {
 		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() {
 		tables << row.vals[0]
 	}
-	res.free()
 	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)
 	C.mysql_real_escape_string_quote(conn.conn, to, s.str, s.len, `\'`)
 	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)
 }
 
-// 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)
 	if C.mysql_get_option(conn.conn, option_type, &ret) != 0 {
 		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
 }
 
-// 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 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
 	}
 	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 {
 		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 
-pub fn (conn Connection) ping() ?bool {
+// has gone down.
+pub fn (mut conn Connection) ping() ?bool {
 	if C.mysql_ping(conn.conn) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
 	}
 	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)
 }
 
-// -------------------------- 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))
 }
 
-// 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.
+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`.
+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)
 }
 
-// --------------------------------- 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 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
 	}
 	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) {
 	C.mysql_debug(debug.str)
 }

vlib/mysql/result.v

@@ -9,86 +9,6 @@ pub mut:
 	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 {
 	name             string
 	org_name         string
@@ -112,6 +32,93 @@ pub struct Field {
 	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 {
 	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)
 }

vlib/mysql/utils.v

@@ -1,16 +1,16 @@
 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 {
 	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 {
 	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 {
 	if isnil(ptr) {
 		return ''