Skip to content
MySQL Client API written entirely in Go
Go Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Sorry for my poor English. If you can help with improving the English in this documentation, please contact me.

MyMySQL v0.4.8 (2012-08-29)

This package contains MySQL client API written entirely in Go. It works with the MySQL protocol version 4.1 or greater. It definitely works well with MySQL 5.0 and 5.1 (I use these versions of MySQL servers for my applications).



New methods for obtain only first/last row from result set. Better implementation of discarding rows in End method.


ScanRow and MakeRow methods addad. ScanRow is more efficient than GetRow because it doesn't allocate memory for every row received from the server. godrv Value.Next method now uses the new ScanRow method.


StatusOnly method added to mysql.Result.


New autorc.Conn.PrepareOnce method.


  1. Row.Int, Row.Uint, Row.Int64, ... methods now panic in case of error.
  2. New Row.Float method.


  1. Fixed issue with panic when the server returns MYSQL_TYPE_NEWDECIMAL.
  2. Decimals are returned as float64 (previously they were returned as []byte).


  1. A lot of changes with MySQL time handling:

  • Datetime type replaced by time.Time.
  • Time type replaced by time.Duration.
  • Support for time.Time type added to godrv.

  1. row.Int64/row.Uint64 methods added.

  2. Rename BindParams to Bind.


BindParams supports Go bool type.


  1. Modular design:

  • MySQL wire protocol handling moved to mymysql/native
  • Thread safe wrapper of native engine in separate mymysql/thrsafe
  • mymysql/mysql package contains definitions of interfaces to engines and common (engine-independent) functions.
  • Automatic reconnect interface moved to mymysql/autorc.

  1. mysql.New and other functions returns mostly interface types. So all previously exported members were converted to methods (with except mysql.Row and mysql.Field - their definition didn't changed).

  2. Transactions added. If you use *mymysql/thrsafe" engine transactions are fully thread safe.

  3. Driver for exp/sql.


To install all subpackages of mymysql you need to goinstal three of them:

$ go get
$ go get
$ go get

go get automagically selects the proper version of mymysql for your Go release. After this command mymysql is ready to use.


For testing you will need to create the test database and a test user:

mysql> create database test;
mysql> grant all privileges on test.* to testuser@localhost;
mysql> set password for testuser@localhost = password("TestPasswd9")

Make sure that MySQL max_allowed_packet variable in my.cnf is equal or greater than 34M (In order to test long packets).

The default MySQL server address is

Next run tests:

$ cd $GOPATH/src/
$ ./all.bash test


Example 1

package main

import (
    _ "" // Native engine
    // _ "" // Thread safe engine

func main() {
    db := mysql.New("tcp", "", "", user, pass, dbname)

    err := db.Connect()
    if err != nil {

    rows, res, err := db.Query("select * from X where id > %d", 20)
    if err != nil {

    for _, row := range rows {
        for _, col := range row {
            if col == nil {
                // col has NULL value
            } else {
                // Do something with text in col (type []byte)
        // You can get specific value from a row
        val1 := row[1].([]byte)

        // You can use it directly if conversion isn't needed

        // You can get converted value
        number := row.Int(0)      // Zero value
        str    := row.Str(1)      // First value
        bignum := row.MustUint(2) // Second value

        // You may get values by column name
        first := res.Map("FirstColumn")
        second := res.Map("SecondColumn")
        val1, val2 := row.Int(first), row.Str(second)

If you do not want to load the entire result into memory you may use Start and GetRow methods:

res, err := db.Start("select * from X")

// Print fields names
for _, field := range res.Fields() {
    fmt.Print(field.Name, " ")

// Print all rows
for {
    row, err := res.GetRow()

    if row == nil {
        // No more rows

    // Print all cols
    for _, col := range row {
        if col == nil {
        } else {
        fmt.Print(" ")

GetRow method allocates a new chunk of memory for every received row. If your query returns hundreds of rows you should opt for the ScanRow method to avoid unnecessary allocations:

// Print all rows
row := res.MakeRow()
for {
    err := res.ScanRow(row)
    if err == io.EOF {
        // No more rows

    // Print all cols
    // [...]

Example 2 - prepared statements

You can use Run or Exec method for prepared statements:

stmt, err := db.Prepare("insert into X values (?, ?)")

type Data struct {
    Id  int
    Tax *float32 // nil means NULL

data = new(Data)

for {
    err := getData(data)
    if err == endOfData {

    _, err = stmt.Run(data.Id, data.Tax)

getData is the function which retrieves data from somewhere and set Id and Tax fields of the Data struct. In the case of Tax field getData may assign a pointer the retrieved variable or nil if NULL should be stored in database.

If you pass parameters to Run or Exec method, the data is rebound on every method call. This isn't efficient if the statement will be executed more than once. You can bind parameters and use Run or Exec method without parameters, to avoid these unnecessary rebinds. Warning! If you use Bind in multithreaded applications, you should ensure that no other thread will use Bind for the same statement, until you no longer need bound parameters.

The simplest way to bind parameters is:

stmt.Bind(data.Id, data.Tax)

but you can't use it in our example, because parameters bound this way can't be changed by getData function. You may modify bindings like this:

stmt.Bind(&data.Id, &data.Tax)

and now it should work properly. But in our example there is better solution:


If Bind method has one parameter, and this parameter is a struct or a pointer to the struct, it treats all fields of this struct as parameters and binds them.

This is the improved code of the previous example:

data = new(Data)

for {
    err := getData(data)
    if isEndOfData(error) {

    _, err = stmt.Run()

Example 3 - using SendLongData in conjunction with http.Get

_, err = db.Start("CREATE TABLE web (url VARCHAR(80), content LONGBLOB)")

ins, err := db.Prepare("INSERT INTO web VALUES (?, ?)")

var url string

ins.Bind(&url, []byte(nil)) // []byte(nil) for properly type binding

for  {
    // Read URL from stdin
    url = ""
    if len(url) == 0 {
        // Stop reading if URL is blank line

    // Make a connection
    resp, err := http.Get(url)

    // We can retrieve response directly into database because 
    // the resp.Body implements io.Reader. Use 8 kB buffer.
    err = ins.SendLongData(1, resp.Body, 8192)

    // Execute insert statement
    _, err = ins.Run()

Example 4 - multi statement / multi result

res, err := db.Start("select id from M; select name from M")

// Get result from first select
for {
    row, err := res.GetRow()
    if row == nil {
        // End of first result

    // Do something with with the data

// Get result from second select
res, err = res.NextResult()
if res == nil {
    panic("Hmm, there is no result. Why?!")
for {
    row, err := res.GetRow()
    if row == nil {
        // End of second result

    // Do something with with the data

Example 5 - transactions

import (
    _ "" // for thread safe transactions
// [...]

// Statement prepared before transaction begins
ins, err := db.Prepare("insert A values (?, ?)")

// Begin a new transaction
tr, err := db.Begin()

// Now db is locked, so any method that uses db and sends commands to
// MySQL server will be blocked until Commit or Rollback is called.

// Commands in transaction are thread safe to
go func() {
    _, err = tr.Start("insert A values (1, 'jeden')")
} ()
_, err = tr.Start("insert A values (2, 'dwa')")

// You can't use statements prepared before transaction in the usual way,
// because the connection is locked by the Begin method. You must bind the statement
// to the transaction before using it.
_, err = tr.Do(ins).Run(3, "three")

// For a greater number of calls
ti := tr.Do(ins)
_, err = ti.Run(4, "four")
_, err = ti.Run(5, "five")

// At the end you can Commit or Rollback. tr is invalidated and using it
// after Commit/Rollback will cause a panic.

Example 6 - autoreconn interface

import (
    _ "" // You may also use the native engine

// [...]

db := autorc.New("tcp", "", "", user, pass, dbname)

// Initilisation commands. They will be executed after each connect.
db.Raw.Register("set names utf8")

// There is no need to explicity connect to the MySQL server
rows, res, err := db.Query("SELECT * FROM R")

// Now we are connected.

// It does not matter if connection will be interrupted during sleep, eg
// due to server reboot or network down.

// If we can reconnect in no more than db.MaxRetries attempts this
// statement will be prepared.
sel, err := db.Prepare("SELECT name FROM R where id > ?")

// We can destroy our connection server side
_, _, err = db.Query("kill %d", db.Raw.ThreadId())

// But it doesn't matter
rows, res, err = sel.Exec()

Example 7 - use database/sql with mymysql driver

// Open new connection. The uri need to have the following syntax:
// where protocol specific part may be empty (this means connection to
// local server using default protocol). Currently possible forms:

// Register initialisation commands
// (workaround, see
godrv.Register("SET NAMES latin2") // Overrides default utf8
godrv.Register("CREATE TABLE IF NOT EXISTS my_table ( ... )")

// Create a connection handler
db, err := sql.Open("mymysql", "test/testuser/TestPasswd9")

// For other information about database/sql see its documentation.

ins, err := db.Prepare("INSERT my_table SET txt=?")

res, err := ins.Exec("some text")

id, err := res.LastInsertId()


rows, err := db.Query("SELECT * FROM go")

for rows.Next() {
    var id int
    var txt string
    checkErr(rows.Scan(&id, &txt))
    // Do something with id and txt


Example 8 - use stored procedures

import (
    _ "" // or native

// [...]

res, err := my.Start("CALL MyProcedure(1, 2, 3)")

// Procedure can return more than one result set so we have to read all
// results up to the result that doesn't include result set (status only
// result).
for !res.StatusOnly() {
    rows, err := res.GetRows()


    res, err := res.NextResult()
    if res == nil {
        panic("nil result from procedure")

Additional examples are in examples directory.

Type mapping

In the case of classic text queries, all variables that are sent to the MySQL server are embedded in the text query. Thus you always convert them to a string and send them embedded in an SQL query:

rows, res, err := db.Query("select * from X where id > %d", id)

After text query you always receive a text result. Mysql text result corresponds to []byte type in mymysql. It isn't string type due to avoidance of unnecessary type conversions. You can always convert []byte to string yourself:


or using Str helper method:


There are other helper methods for data conversion like Int or Uint:


All three above examples return value received in row 0 column 1. If you prefer to use the column names, you can use res.Map which maps result field names to corresponding indexes:

name := res.Map("name")

In case of prepared statements, the type mapping is slightly more complicated. For parameters sent from the client to the server, Go/mymysql types are mapped for MySQL protocol types as below:

         string  -->  MYSQL_TYPE_STRING
         []byte  -->  MYSQL_TYPE_VAR_STRING
    int8, uint8  -->  MYSQL_TYPE_TINY
  int16, uint16  -->  MYSQL_TYPE_SHORT
  int32, uint32  -->  MYSQL_TYPE_LONG
  int64, uint64  -->  MYSQL_TYPE_LONGLONG
      int, uint  -->  protocol integer type which match size of int
           bool  -->  MYSQL_TYPE_TINY
        float32  -->  MYSQL_TYPE_FLOAT
        float64  -->  MYSQL_TYPE_DOUBLE
      time.Time  -->  MYSQL_TYPE_DATETIME
mysql.Timestamp  -->  MYSQL_TYPE_TIMESTAMP
     mysql.Date  -->  MYSQL_TYPE_DATE
  time.Duration  -->  MYSQL_TYPE_TIME
     mysql.Blob  -->  MYSQL_TYPE_BLOB
            nil  -->  MYSQL_TYPE_NULL

The MySQL server maps/converts them to a particular MySQL storage type.

For received results MySQL storage types are mapped to Go/mymysql types as below:

                             TINYINT  -->  int8
                    UNSIGNED TINYINT  -->  uint8
                            SMALLINT  -->  int16
                   UNSIGNED SMALLINT  -->  uint16
                      MEDIUMINT, INT  -->  int32
                              BIGINT  -->  int64
                     UNSIGNED BIGINT  -->  uint64
                               FLOAT  -->  float32
                              DOUBLE  -->  float64
                             DECIMAL  -->  float64
                 TIMESTAMP, DATETIME  -->  time.Time
                                DATE  -->  mysql.Date
                                TIME  -->  time.Duration
                                YEAR  -->  int16
                                 BIT  -->  []byte
                           SET, ENUM  -->  []byte
                                NULL  -->  nil

Big packets

This package can send and receive MySQL data packets that are biger than 16 MB. This means that you can receive response rows biger than 16 MB and can execute prepared statements with parameter data bigger than 16 MB without using SendLongData method. If you want to use this feature you need to change the default mymysql setting using the Conn.SetMaxPktSize method and change max_allowed_packet value in your MySQL server configuration.

Thread safe engine

If you import "mymysql/thrsafe" engine instead of "mymysql/native" engine all methods are thread safe, unless the description of the method says something else.

If one thread is calling Query or Exec method, other threads will be blocked if they call Query, Start, Exec, Run or other method which send data to the server, until Query/Exec return in first thread.

If one thread is calling Start or Run method, other threads will be blocked if they call Query, Start, Exec, Run or other method which send data to the server, until all results and all rows will be readed from the connection in first thread.

In most of my web applications I use the autorecon interface with thrsafe engine. For any new connection, one gorutine is created. There is one persistant connection to MySQL server shared by all gorutines. Applications are usually running on dual-core machines with GOMAXPROCS=2. I use siege to test any application befor put it into production. There is example output from siege:

# siege -c25 -d0 -t 30s
** SIEGE 2.69
** Preparing 25 concurrent users for battle.
The server is now under siege...
Lifting the server siege..      done.
Transactions:                   3212 hits
Availability:                 100.00 %
Elapsed time:                  29.83 secs
Data transferred:               3.88 MB
Response time:                  0.22 secs
Transaction rate:             107.68 trans/sec
Throughput:                     0.13 MB/sec
Concurrency:                   23.43
Successful transactions:        3218
Failed transactions:               0
Longest transaction:            9.28
Shortest transaction:           0.01

To do

  1. Transactions in auto reconnect interface.
  2. Complete documentation

Known bugs

  1. There is MySQL "bug" in the SUM function. If you use prepared statements SUM returns DECIMAL value, even if you sum integer column. mymysql returns decimals as float64 so cast result from sum to integer (or use Row.Int) causes panic.


mysql native thrsafe autorc godrv

Something went wrong with that request. Please try again.