go-sql-driver / mysql

Go-MySQL-Driver A MySQL-Driver for Go's database/sql package --------------------------------------- • Features • Requirements • Installation • Usage • DSN (Data Source Name) • Password • Protocol • Address • Parameters • Examples • Connection pool and timeouts • context.Context Support • ColumnType Support • LOAD DATA LOCAL INFILE support • time.Time support • Unicode support • Testing / Development • License --------------------------------------- Features • Lightweight and fast • Native Go implementation. No C-bindings, just pure Go • Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets or custom protocols • Automatic handling of broken connections • Automatic Connection Pooling *(by database/sql package)* • Supports queries larger than 16MB • Full support. • Intelligent handling in prepared statements • Secure support with file allowlisting and support • Optional parsing • Optional placeholder interpolation • Supports zlib compression. Requirements • Go 1.22 or higher. We aim to support the 3 latest versions of Go. • MySQL (5.7+) and MariaDB (10.5+) are supported. • TiDB is supported by PingCAP. • Do not ask questions about TiDB in our issue tracker or forum. • Document • Forum • go-mysql would work with Percona Server, Google CloudSQL or Sphinx (2.2.3+). • Maintainers won't support them. Do not expect issues are investigated and resolved by maintainers. • Investigate issues yourself and please send a pull request to fix it. --------------------------------------- Installation Simple install the package to your $GOPATH with the go tool from shell: Make sure Git is installed on your machine and in your system's . Usage _Go MySQL Driver_ is an implementation of Go's interface. You only need to import the driver and can use the full API then. Use as and a valid DSN as : Examples are available in our Wiki. Important settings is required to ensure connections are closed by the driver safely before connection is closed by MySQL server, OS, or other middlewares. Since some middlewares close idle connections by 5 minutes, we recommend timeout shorter than 5 minutes. This setting helps load balancing and changing system variables too. is highly recommended to limit the number of connection used by the application. There is no recommended limit number because it depends on application and MySQL server. is recommended to be set same to . When it is smaller than , connections can be opened and closed much more frequently than you expect. Idle connections can be closed by the . If you want to close idle connections more rapidly, you can use since Go 1.15. DSN (Data Source Name) The Data Source Name has a common format, like e.g. PEAR DB uses it, but without type-prefix (optional parts marked by squared brackets): A DSN in its fullest form: Except for the databasename, all values are optional. So the minimal DSN is: If you do not want to preselect a database, leave empty: This has the same effect as an empty DSN string: is escaped by PathEscape() since v1.8.0. If your database name is , it becomes: Alternatively, Config.FormatDSN can be used to create a DSN string by filling a struct. Password Passwords can consist of any character. Escaping is **not** necessary. Protocol See net.Dial for more information which networks are available. In general you should use a Unix domain socket if available and TCP otherwise for best performance. Address For TCP and UDP networks, addresses have the form . If is omitted, the default port will be used. If is a literal IPv6 address, it must be enclosed in square brackets. The functions net.JoinHostPort and net.SplitHostPort manipulate addresses in this form. For Unix domain sockets the address is the absolute path to the MySQL-Server-socket, e.g. or . Parameters *Parameters are case-sensitive!* Notice that any of , , or is accepted to stand for a true boolean value. Not surprisingly, false can be specified as any of: , , or . disables the file allowlist for and allows *all* files. *Might be insecure!* allows using the cleartext client side plugin if required by an account, such as one defined with the PAM authentication plugin. Sending passwords in clear text may be a security problem in some configurations. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a method that protects the password. Possibilities include TLS / SSL, IPsec, or a private network. acts like a MySQL client as described in Command Options for Connecting to the Server disallows the usage of MySQL native password method. allows the usage of the insecure old password method. This should be avoided, but is necessary in some cases. See also the old_passwords wiki page. Sets the charset used for client-server interaction ( ). If multiple charsets are set (separated by a comma), the following charset is used if setting the charset fails. This enables for example support for (introduced in MySQL 5.5.3) with fallback to for older servers ( ). See also Unicode Support. On supported platforms connections retrieved from the connection pool are checked for liveness before using them. If the check fails, the respective connection is marked as bad and the query retried with another connection. disables this liveness check of connections. Sets the collation used for client-server interaction on connection. In contrast to , does not issue additional queries. If the specified collation is unavailable on the target server, the connection will fail. A list of valid charsets for a server is retrievable with . The default collation ( ) is supported from MySQL 5.5. You should use an older collation (e.g. ) for older MySQL. Collations for charset "ucs2", "utf16", "utf16le", and "utf32" can not be used (ref). See also Unicode Support. causes an UPDATE to return the number of matching rows instead of the number of rows changed. When is true, calls to will return the table alias and the…