|
1 | | -# Go-MySQL-Driver |
2 | | - |
3 | | -A MySQL-Driver for Go's [database/sql](http://golang.org/pkg/database/sql) package |
4 | | - |
5 | | - |
6 | | - |
7 | | -**Current tagged Release:** January 08, 2013 *(beta)* |
8 | | - |
9 | | -[](https://travis-ci.org/Go-SQL-Driver/MySQL) *(master branch)* |
10 | | - |
11 | | -Note: `go get` doesn't install the master branch, but the tag `go1`, which is always checked before tagging! |
12 | | - |
13 | | ---------------------------------------- |
14 | | - * [Features](#features) |
15 | | - * [Requirements](#requirements) |
16 | | - * [Installation](#installation) |
17 | | - * [Usage](#usage) |
18 | | - * [DSN (Data Source Name)](#dsn-data-source-name) |
19 | | - * [Password](#password) |
20 | | - * [Protocol](#protocol) |
21 | | - * [Address](#address) |
22 | | - * [Parameters](#parameters) |
23 | | - * [Examples](#examples) |
24 | | - * [License](#license) |
25 | | - |
26 | | ---------------------------------------- |
27 | | - |
28 | | -## Features |
29 | | - * Lightweight and fast |
30 | | - * Native Go implementation. No C-bindings, just pure Go |
31 | | - * No unsafe operations *(type-conversions etc.)* |
32 | | - |
33 | | -## Requirements |
34 | | - * Go 1 or higher (Go 1.0.3 or higher recommended) |
35 | | - * MySQL (Version 4.1 or higher), MariaDB or Percona Server |
36 | | - |
37 | | ---------------------------------------- |
38 | | - |
39 | | -## Installation |
40 | | -Simple install the package with the go tool from shell: |
41 | | -```bash |
42 | | -$ go get github.com/Go-SQL-Driver/MySQL |
43 | | -``` |
44 | | -Make sure [Git is installed](http://git-scm.com/downloads) on your machine and in your system's `PATH`. |
45 | | - |
46 | | -## Usage |
47 | | -_Go MySQL Driver_ is an implementation of Go's `database/sql/driver` interface, so all you need to do is import the driver and open a new Database-Connection with the given driver. |
48 | | - |
49 | | -Use `"mysql"` as `driverName` and a valid [DSN](#dsn-data-source-name) as `dataSourceName` |
50 | | -```go |
51 | | -import "database/sql" |
52 | | -import _ "code.google.com/p/go-mysql-driver/mysql" |
53 | | - |
54 | | -db, e := sql.Open("mysql", "user:password@/dbname?charset=utf8") |
55 | | -``` |
56 | | - |
57 | | -All further methods are listed here: http://golang.org/pkg/database/sql |
58 | | - |
59 | | - |
60 | | -## DSN (Data Source Name) |
61 | | - |
62 | | -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: |
63 | | -``` |
64 | | -[username[:password]@][protocol[(address)]]/dbname[?param1=value1¶mN=valueN] |
65 | | -``` |
66 | | - |
67 | | -A DSN in its fullest form: |
68 | | -``` |
69 | | -username:password@protocol(address)/dbname?param=value |
70 | | -``` |
71 | | - |
72 | | -Except of the databasename, all values are optional. So the minimal DSN is: |
73 | | -``` |
74 | | -/dbname |
75 | | -``` |
76 | | - |
77 | | -If you do not want to preselect a database, leave `dbname` empty: |
78 | | -``` |
79 | | -/ |
80 | | -``` |
81 | | - |
82 | | -### Password |
83 | | -Passwords can consist of any character. Escaping is not necessary. |
84 | | - |
85 | | -### Protocol |
86 | | -See [net.Dial](http://golang.org/pkg/net/#Dial) for more information which networks are available. |
87 | | -In general you should use an Unix-socket if available and TCP otherwise for best performance. |
88 | | - |
89 | | -### Address |
90 | | -For TCP and UDP networks, addresses have the form `host:port`. |
91 | | -If `host` is a literal IPv6 address, it must be enclosed in square brackets. |
92 | | -The functions [net.JoinHostPort](http://golang.org/pkg/net/#JoinHostPort) and [net.SplitHostPort](http://golang.org/pkg/net/#SplitHostPort) manipulate addresses in this form. |
93 | | - |
94 | | -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`. |
95 | | - |
96 | | -### Parameters |
97 | | -**Parameters are case-sensitive!** |
98 | | - |
99 | | -Possible Parameters are: |
100 | | - * `charset`: *"SET NAMES `value`"* |
101 | | - * _(deprecated)_ <s>`keepalive`: If `value` equals 1, the keepalive-time is set to [wait_timeout](https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_wait_timeout)-60, which pings the Server 60 seconds before the MySQL server would close the connection to avoid timeout. If the value is greater than 1, the server gets pinged every `value` seconds without a command. System variables are executed **before**, so it may be possible to change the *wait_timeout* value.</s> **With Go 1.0.3 this is not necessary anymore. Now closed connections can be automatically detected and handled.** |
102 | | - * _(pending)_ <s>`tls`</s>: will enable SSL/TLS-Encryption |
103 | | - * _(pending)_ <s>`compress`</s>: will enable Compression |
104 | | - |
105 | | -All other parameters are interpreted as system variables: |
106 | | - * `time_zone`: *"SET time_zone='`value`'"* |
107 | | - * `tx_isolation`: *"SET [tx_isolation](https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_tx_isolation)='`value`'"* |
108 | | - * `param`: *"SET `param`=`value`"* |
109 | | - |
110 | | -### Examples |
111 | | -``` |
112 | | -user@unix(/path/to/socket)/dbname?charset=utf8 |
113 | | -``` |
114 | | - |
115 | | -``` |
116 | | -user:password@tcp(localhost:5555)/dbname?charset=utf8 |
117 | | -``` |
118 | | - |
119 | | -``` |
120 | | -user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname |
121 | | -``` |
122 | | - |
123 | | -``` |
124 | | -user:password@/dbname |
125 | | -``` |
126 | | - |
127 | | -No Database preselected: |
128 | | -``` |
129 | | -user:password@/ |
130 | | -``` |
131 | | - |
132 | | ---------------------------------------- |
133 | | - |
134 | | -## License |
135 | | -Go-MySQL-Driver is licensed under the [Mozilla Public License Version 2.0](https://raw.github.com/Go-SQL-Driver/MySQL/master/LICENSE) |
136 | | - |
137 | | -Mozilla summarizes the license scope as follows: |
138 | | -> MPL: The copyleft applies to any files containing MPLed code. |
139 | | -
|
140 | | - |
141 | | -That means: |
142 | | - * You can **use** the **unchanged** source code both in private as also commercial |
143 | | - * You **needn't publish** the source code of your library as long the files licensed under the MPL 2.0 are **unchanged** |
144 | | - * 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) |
145 | | - |
146 | | -Please read the [MPL 2.0 FAQ](http://www.mozilla.org/MPL/2.0/FAQ.html) if you have further questions regarding the license. |
147 | | - |
148 | | -You can read the full terms here: [LICENSE](https://raw.github.com/Go-SQL-Driver/MySQL/master/LICENSE) |
| 1 | +# [Go-MySQL-Driver](https://github.com/Go-SQL-Driver/MySQL "Pure Go lightweight and fast MySQL-Driver") |
0 commit comments