mysql,client,driver: Add more docs/comments and update constants (#974)

* mysql,client: Add more docs/comments and update constants

* Add comment to UseSslOption

---------

Co-authored-by: lance6716 <lance6716@gmail.com>

Author: dveeden

client/conn.go

@@ -194,10 +194,12 @@ func (c *Conn) handshake() error {
 	return nil
 }
 
+// Close directly closes the connection. Use Quit() to first send COM_QUIT to the server and then close the connection.
 func (c *Conn) Close() error {
 	return c.Conn.Close()
 }
 
+// Quit sends COM_QUIT to the server and then closes the connection. Use Close() to directly close the connection.
 func (c *Conn) Quit() error {
 	if err := c.writeCommand(COM_QUIT); err != nil {
 		return err
@@ -375,6 +377,7 @@ func (c *Conn) Rollback() error {
 	return errors.Trace(err)
 }
 
+// SetAttributes sets connection attributes
 func (c *Conn) SetAttributes(attributes map[string]string) {
 	for k, v := range attributes {
 		c.attributes[k] = v
@@ -407,6 +410,7 @@ func (c *Conn) GetCollation() string {
 	return c.collation
 }
 
+// FieldList uses COM_FIELD_LIST to get a list of fields from a table
 func (c *Conn) FieldList(table string, wildcard string) ([]*Field, error) {
 	if err := c.writeCommandStrStr(COM_FIELD_LIST, table, wildcard); err != nil {
 		return nil, errors.Trace(err)
@@ -446,10 +450,12 @@ func (c *Conn) SetAutoCommit() error {
 	return nil
 }
 
+// IsAutoCommit returns true if SERVER_STATUS_AUTOCOMMIT is set
 func (c *Conn) IsAutoCommit() bool {
 	return c.status&SERVER_STATUS_AUTOCOMMIT > 0
 }
 
+// IsInTransaction returns true if SERVER_STATUS_IN_TRANS is set
 func (c *Conn) IsInTransaction() bool {
 	return c.status&SERVER_STATUS_IN_TRANS > 0
 }
@@ -485,6 +491,7 @@ func (c *Conn) exec(query string) (*Result, error) {
 
 // CapabilityString is returning a string with the names of capability flags
 // separated by "|". Examples of capability names are CLIENT_DEPRECATE_EOF and CLIENT_PROTOCOL_41.
+// These are defined as constants in the mysql package.
 func (c *Conn) CapabilityString() string {
 	var caps []string
 	capability := c.capability
@@ -568,6 +575,8 @@ func (c *Conn) CapabilityString() string {
 	return strings.Join(caps, "|")
 }
 
+// StatusString returns a "|" separated list of status fields. Example status values are SERVER_QUERY_WAS_SLOW and SERVER_STATUS_AUTOCOMMIT.
+// These are defined as constants in the mysql package.
 func (c *Conn) StatusString() string {
 	var stats []string
 	status := c.status

driver/driver_options.go

@@ -12,6 +12,8 @@ import (
 // The value represents the query string parameter value supplied by in the DNS.
 type DriverOption func(c *client.Conn, value string) error
 
+// UseSslOption sets the connection to use a tls.Config with InsecureSkipVerify set to true.
+// Use SetTLSConfig() if you need a custom tls.Config
 func UseSslOption(c *client.Conn) error {
 	c.UseSSL(true)
 	return nil

mysql/const.go

@@ -26,6 +26,9 @@ const (
 	AUTH_SHA256_PASSWORD       = "sha256_password"
 )
 
+// SERVER_STATUS_flags_enum
+// https://dev.mysql.com/doc/dev/mysql-server/latest/mysql__com_8h.html#a1d854e841086925be1883e4d7b4e8cad
+// https://github.com/mysql/mysql-server/blob/500c3117e6f638043c4fea8aacf17d63a8d07de6/include/mysql_com.h#L809-L864
 const (
 	SERVER_STATUS_IN_TRANS             uint16 = 0x0001
 	SERVER_STATUS_AUTOCOMMIT           uint16 = 0x0002
@@ -39,8 +42,11 @@ const (
 	SERVER_STATUS_METADATA_CHANGED     uint16 = 0x0400
 	SERVER_QUERY_WAS_SLOW              uint16 = 0x0800
 	SERVER_PS_OUT_PARAMS               uint16 = 0x1000
+	SERVER_STATUS_IN_TRANS_READONLY    uint16 = 0x2000
+	SERVER_SESSION_STATE_CHANGED       uint16 = 0x4000
 )
 
+// https://github.com/mysql/mysql-server/blob/6b6d3ed3d5c6591b446276184642d7d0504ecc86/include/my_command.h#L48-L103
 const (
 	COM_SLEEP byte = iota
 	COM_QUIT
@@ -74,6 +80,8 @@ const (
 	COM_DAEMON
 	COM_BINLOG_DUMP_GTID
 	COM_RESET_CONNECTION
+	COM_CLONE
+	COM_SUBSCRIBE_GROUP_REPLICATION_STREAM
 )
 
 const (