README.md

# Go-MySQL-Driver

A MySQL-Driver for Go's [database/sql](http://golang.org/pkg/database/sql) package

![Go-MySQL-Driver logo](https://raw.github.com/wiki/Go-SQL-Driver/MySQL/go-mysql-driver_m.jpg "Golang Gopher transporting the MySQL Dolphin in a wheelbarrow")

**Current tagged Release:** February 25, 2013 (stable beta 3)

[![Build Status](https://travis-ci.org/Go-SQL-Driver/MySQL.png?branch=master)](https://travis-ci.org/Go-SQL-Driver/MySQL) *(master branch)*

---------------------------------------
  * [Features](#features)
  * [Requirements](#requirements)
  * [Installation](#installation)
  * [Usage](#usage)
  * [DSN (Data Source Name)](#dsn-data-source-name)
    * [Password](#password)
    * [Protocol](#protocol)
    * [Address](#address)
    * [Parameters](#parameters)
    * [Examples](#examples)
  * [Testing / Development](#testing--development)
  * [License](#license)

---------------------------------------

## Features
  * Lightweight and fast
  * Native Go implementation. No C-bindings, just pure Go
  * No unsafe operations *(e.g. type-conversions)*
  * Connections over TCP/IPv4, TCP/IPv6 or Unix Sockets
  * Automatic handling of broken connections
  * Automatic Connection-Pooling *(by database/sql package)*

## Requirements
  * Go 1.0.3 or higher
  * MySQL (Version 4.1 or higher), MariaDB or Percona Server

---------------------------------------

## Installation
Simple install the package to your [$GOPATH](http://code.google.com/p/go-wiki/wiki/GOPATH "GOPATH") with the [go tool](http://golang.org/cmd/go/ go command) from shell:
```bash
$ go get github.com/Go-SQL-Driver/MySQL
```
Make sure [Git is installed](http://git-scm.com/downloads) on your machine and in your system's `PATH`.

## Usage
_Go MySQL Driver_ is an implementation of Go's `database/sql/driver` interface, so all you need to do is to import the driver and open a new database connection with the given driver.

Use `mysql` as `driverName` and a valid [DSN](#dsn-data-source-name)  as `dataSourceName`
```go
import "database/sql"
import _ "github.com/Go-SQL-Driver/MySQL"

db, e := sql.Open("mysql", "user:password@/dbname?charset=utf8")
```

All further methods are listed here: http://golang.org/pkg/database/sql

[Examples are available in our Wiki](https://github.com/Go-SQL-Driver/MySQL/wiki/Examples "Go-MySQL-Driver Examples").


## DSN (Data Source Name)

The Data Source Name has a common format, like e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php) uses it, but without type-prefix (optional parts marked by squared brackets):
```
[username[:password]@][protocol[(address)]]/dbname[?param1=value1&paramN=valueN]
```

A DSN in its fullest form:
```
username:password@protocol(address)/dbname?param=value
```

Except of the databasename, all values are optional. So the minimal DSN is:
```
/dbname
```

If you do not want to preselect a database, leave `dbname` empty:
```
/
```

### Password
Passwords can consist of any character. Escaping is **not** necessary.

### Protocol
See [net.Dial](http://golang.org/pkg/net/#Dial) for more information which networks are available.
In general you should use an Unix-socket if available and TCP otherwise for best performance.

### Address
For TCP and UDP networks, addresses have the form `host:port`.
If `host` is a literal IPv6 address, it must be enclosed in square brackets.
The functions [net.JoinHostPort](http://golang.org/pkg/net/#JoinHostPort) and [net.SplitHostPort](http://golang.org/pkg/net/#SplitHostPort) manipulate addresses in this form.

For Unix-sockets the address is the absolute path to the MySQL-Server-socket, e.g. `/var/run/mysqld/mysqld.sock` or `/tmp/mysql.sock`.

### Parameters
**Parameters are case-sensitive!**

Possible Parameters are:
  * `charset`: *"SET NAMES `value`"*. If multiple charsets are set (seperated by a comma), the following charset is used if setting the charset failes. This enables support for `utf8mb4` ([introduced in MySQL 5.5.3](http://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html)) with fallback to `utf8` for older servers.
  * _(pending)_ <s>`tls`</s>: will enable SSL/TLS-Encryption
  * _(pending)_ <s>`compress`</s>: will enable Compression

All other parameters are interpreted as system variables:
  * `time_zone`: *"SET time_zone='`value`'"*
  * `tx_isolation`: *"SET [tx_isolation](https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_tx_isolation)='`value`'"*
  * `param`: *"SET `param`=`value`"*

### Examples
```
user@unix(/path/to/socket)/dbname?charset=utf8
```

```
user:password@tcp(localhost:5555)/dbname?charset=utf8mb4,utf8
```

```
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname
```

```
user:password@/dbname
```

No Database preselected:
```
user:password@/
```

## Testing / Development
To run the driver tests you may need to adjust the configuration. See [this Wiki-Page](https://github.com/Go-SQL-Driver/MySQL/wiki/Testing "Testing") for details.

---------------------------------------

## License
Go-MySQL-Driver is licensed under the [Mozilla Public License Version 2.0](https://raw.github.com/Go-SQL-Driver/MySQL/master/LICENSE)

Mozilla summarizes the license scope as follows:
> MPL: The copyleft applies to any files containing MPLed code.


That means:
  * You can **use** the **unchanged** source code both in private as also commercial
  * You **needn't publish** the source code of your library as long the files licensed under the MPL 2.0 are **unchanged**
  * You **must publish** the source code of any **changed files** licensed under the MPL 2.0 under a) the MPL 2.0 itself or b) a compatible license (e.g. GPL 3.0 or Apache License 2.0)

Please read the [MPL 2.0 FAQ](http://www.mozilla.org/MPL/2.0/FAQ.html) if you have further questions regarding the license.

You can read the full terms here: [LICENSE](https://raw.github.com/Go-SQL-Driver/MySQL/master/LICENSE)