diff options
Diffstat (limited to 'Godeps/_workspace/src/github.com/go-gorp/gorp/README.md')
| -rw-r--r-- | Godeps/_workspace/src/github.com/go-gorp/gorp/README.md | 119 |
1 files changed, 88 insertions, 31 deletions
diff --git a/Godeps/_workspace/src/github.com/go-gorp/gorp/README.md b/Godeps/_workspace/src/github.com/go-gorp/gorp/README.md index d2de8c2b6..3f0652bc7 100644 --- a/Godeps/_workspace/src/github.com/go-gorp/gorp/README.md +++ b/Godeps/_workspace/src/github.com/go-gorp/gorp/README.md @@ -1,19 +1,26 @@ # Go Relational Persistence -[](http://travis-ci.org/go-gorp/gorp) +[](http://travis-ci.org/go-gorp/gorp) +[](https://coveralls.io/r/go-gorp/gorp) +[](https://github.com/go-gorp/gorp/issues) +[](https://godoc.org/gopkg.in/gorp.v1) +[](https://godoc.org/github.com/go-gorp/gorp) -I hesitate to call gorp an ORM. Go doesn't really have objects, at least -not in the classic Smalltalk/Java sense. There goes the "O". gorp doesn't -know anything about the relationships between your structs (at least not -yet). So the "R" is questionable too (but I use it in the name because, -well, it seemed more clever). +### Update 2015-07-01 Cleanup & feature freeze ([#270](https://github.com/go-gorp/gorp/issues/270)) -The "M" is alive and well. Given some Go structs and a database, gorp -should remove a fair amount of boilerplate busy-work from your code. +We are currently cleaning up the backlog of issues and PR's. When this is done the codebase will be split into separate files and there will be breaking changes to the API's. We're also adding better tests and documentation. As a result of these changes the `master` branch will be unstable. Please use `gopkg.in/gorp.v1`. When the cleanup and changes are done, we will release `v2.0`. -I hope that gorp saves you time, minimizes the drudgery of getting data -in and out of your database, and helps your code focus on algorithms, -not infrastructure. +At this time we won't accept new feature-related pull-requests because of changes to the codebase. Please create an issue for your feature and wait until `v2.0` has been released. + +For more information, please read [#270](https://github.com/go-gorp/gorp/issues/270). + +## Introduction + +I hesitate to call gorp an ORM. Go doesn't really have objects, at least not in the classic Smalltalk/Java sense. There goes the "O". gorp doesn't know anything about the relationships between your structs (at least not yet). So the "R" is questionable too (but I use it in the name because, well, it seemed more clever). + +The "M" is alive and well. Given some Go structs and a database, gorp should remove a fair amount of boilerplate busy-work from your code. + +I hope that gorp saves you time, minimizes the drudgery of getting data in and out of your database, and helps your code focus on algorithms, not infrastructure. * Bind struct fields to table columns via API or tag * Support for embedded structs @@ -34,7 +41,7 @@ not infrastructure. # install the library: go get gopkg.in/gorp.v1 - + // use in your .go code: import ( "gopkg.in/gorp.v1" @@ -143,10 +150,10 @@ func main() { type Post struct { // db tag lets you specify the column name if it differs from the struct field - Id int64 `db:"post_id"` + Id int64 `db:"post_id"` Created int64 - Title string - Body string + Title string `db:",size:50"` // Column size set to 50 + Body string `db:"article_body,size:1024"` // Set both column name and size } func newPost(title, body string) Post { @@ -201,7 +208,7 @@ type Invoice struct { } type Person struct { - Id int64 + Id int64 Created int64 Updated int64 FName string @@ -221,8 +228,10 @@ type Person struct { // table.ColMap("Price").Rename("unit_price") // table.ColMap("IgnoreMe").SetTransient(true) // +// You can optionally declare the field to be a primary key and/or autoincrement +// type Product struct { - Id int64 `db:"product_id"` + Id int64 `db:"product_id, primarykey, autoincrement"` Price int64 `db:"unit_price"` IgnoreMe string `db:"-"` } @@ -239,7 +248,7 @@ db, err := sql.Open("mymysql", "tcp:localhost:3306*mydb/myuser/mypassword") dbmap := &gorp.DbMap{Db: db, Dialect: gorp.MySQLDialect{"InnoDB", "UTF8"}} // register the structs you wish to use with gorp -// you can also use the shorter dbmap.AddTable() if you +// you can also use the shorter dbmap.AddTable() if you // don't want to override the table name // // SetKeys(true) means we have a auto increment primary key, which @@ -296,13 +305,13 @@ I recommend enabling this initially while you're getting the feel for what gorp is doing on your behalf. Gorp defines a `GorpLogger` interface that Go's built in `log.Logger` satisfies. -However, you can write your own `GorpLogger` implementation, or use a package such +However, you can write your own `GorpLogger` implementation, or use a package such as `glog` if you want more control over how statements are logged. ```go // Will log all SQL statements + args as they are run // The first arg is a string prefix to prepend to all log messages -dbmap.TraceOn("[gorp]", log.New(os.Stdout, "myapp:", log.Lmicroseconds)) +dbmap.TraceOn("[gorp]", log.New(os.Stdout, "myapp:", log.Lmicroseconds)) // Turn off tracing dbmap.TraceOff() @@ -435,7 +444,7 @@ only supported in SELECT queries. ```go _, err := dbm.Select(&dest, "select * from Foo where name = :name and age = :age", map[string]interface{}{ - "name": "Rob", + "name": "Rob", "age": 31, }) ``` @@ -509,11 +518,11 @@ Full list of hooks that you can implement: PostUpdate PreDelete PostDelete - + All have the same signature. for example: - + func (p *MyStruct) PostUpdate(s gorp.SqlExecutor) error - + ### Optimistic Locking #### Note that this behaviour has changed in v2. See [Migration Guide](#migration-guide). @@ -536,7 +545,7 @@ type Person struct { Updated int64 FName string LName string - + // automatically used as the Version col // use table.SetVersionCol("columnName") to map a different // struct field as the version field @@ -558,7 +567,7 @@ count, err := dbmap.Update(p1) _, ok := err.(gorp.OptimisticLockError) if ok { // should reach this statement - + // in a real app you might reload the row and retry, or // you might propegate this to the user, depending on the desired // semantics @@ -568,6 +577,49 @@ if ok { fmt.Printf("Unknown db err: %v\n", err) } ``` +### Adding INDEX(es) on column(s) beyond the primary key ### + +Indexes are frequently critical for performance. Here is how to add them to your tables. + +NB: SqlServer and Oracle need testing and possible adjustment to the +CreateIndexSuffix() and DropIndexSuffix() methods to make AddIndex() +work for them. + +In the example below we put an index both on the Id field, and on the AcctId field. + +``` +type Account struct { + Id int64 + AcctId string // e.g. this might be a long uuid for portability +} + +// indexType (the 2nd param to AddIndex call) is "Btree" or "Hash" for MySQL. +// demonstrate adding a second index on AcctId, and constrain that field to have unique values. +dbm.AddTable(iptab.Account{}).SetKeys(true, "Id").AddIndex("AcctIdIndex", "Btree", []string{"AcctId"}).SetUnique(true) + +err = dbm.CreateTablesIfNotExists() +checkErr(err, "CreateTablesIfNotExists failed") + +err = dbm.CreateIndex() +checkErr(err, "CreateIndex failed") + +``` +Check the effect of the CreateIndex() call in mysql: +``` +$ mysql + +MariaDB [test]> show create table Account; ++---------+--------------------------+ +| Account | CREATE TABLE `Account` ( + `Id` bigint(20) NOT NULL AUTO_INCREMENT, + `AcctId` varchar(255) DEFAULT NULL, + PRIMARY KEY (`Id`), + UNIQUE KEY `AcctIdIndex` (`AcctId`) USING BTREE <<<--- yes! index added. +) ENGINE=InnoDB DEFAULT CHARSET=utf8 ++---------+--------------------------+ + +``` + ## Database Drivers @@ -582,13 +634,13 @@ implemented per database vendor. Dialects are provided for: * PostgreSQL * sqlite3 -Each of these three databases pass the test suite. See `gorp_test.go` for example +Each of these three databases pass the test suite. See `gorp_test.go` for example DSNs for these three databases. Support is also provided for: * Oracle (contributed by @klaidliadon) -* SQL Server (contributed by @qrawl) - use driver: github.com/denisenkom/go-mssqldb +* SQL Server (contributed by @qrawl) - use driver: github.com/denisenkom/go-mssqldb Note that these databases are not covered by CI and I (@coopernurse) have no good way to test them locally. So please try them and send patches as needed, but expect a bit more @@ -598,7 +650,7 @@ unpredicability. ### SQL placeholder portability -Different databases use different strings to indicate variable placeholders in +Different databases use different strings to indicate variable placeholders in prepared SQL statements. Unlike some database abstraction layers (such as JDBC), Go's `database/sql` does not standardize this. @@ -617,13 +669,18 @@ In `Select` and `SelectOne` you can use named parameters to work around this. The following is portable: ```go -err := dbmap.SelectOne(&val, "select * from foo where id = :id", +err := dbmap.SelectOne(&val, "select * from foo where id = :id", map[string]interface{} { "id": 30}) ``` +Additionally, when using Postgres as your database, you should utilize `$1` instead +of `?` placeholders as utilizing `?` placeholders when querying Postgres will result +in `pq: operator does not exist` errors. Alternatively, use +`dbMap.Dialect.BindVar(varIdx)` to get the proper variable binding for your dialect. + ### time.Time and time zones -gorp will pass `time.Time` fields through to the `database/sql` driver, but note that +gorp will pass `time.Time` fields through to the `database/sql` driver, but note that the behavior of this type varies across database drivers. MySQL users should be especially cautious. See: https://github.com/ziutek/mymysql/pull/77 |