mysql: update documentation

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

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)

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)
 }

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)
 }