good morning!!!!

Skip to content
Snippets Groups Projects
Commit f707cd2b authored by José Carlos Nieto's avatar José Carlos Nieto
Browse files

Docs

parent 6b6e6298
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 98 additions and 99 deletions
README.md
+ 98
− 99
View file @ f707cd2b
# gosexy/db # gosexy/db
This package is a wrapper of many third party database drivers. The goal of this abstraction is to provide a common, `gosexy/db` is a set of wrappers for SQL and NoSQL database drivers for Go
simplified and consistent layer for working with different databases without the need of SQL statements. currently compatible with [MongoDB][1], [MySQL][2], [PostgreSQL][3]
and [SQLite3][4].
## Available wrappers The goal of this package is to provide a common, simple, consistent layer of
abstraction for performing mundane operations such as create, read, update,
and delete rows (CRUD) on different databases.
* [mongo](http://gosexy.org/db/wrappers/mongo) While `gosexy/db` is *not* an ORM it can be used as the base for one, that's
* [mysql](http://gosexy.org/db/wrappers/mysql) up to the final user, but `gosexy/db` prefers to stay out of the way.
* [postgresql](http://gosexy.org/db/wrappers/postgresql)
* [sqlite](http://gosexy.org/db/wrappers/sqlite) Let me show you an example, this chunk of code searches on the "people"
table/collection. It does not matter whether we are querying a NoSQL database
like [MongoDB][1] or an SQL database like [MySQL][2], [PostgreSQL][3] or
[SQLite3][4], `gosexy/db` talks to the database in the language the database
expects and returns you a set of results.
```
items, err := people.FindAll(
db.Cond{"name": "john"},
)
for i, item := range items {
// ...
}
```
While this level of abstraction would not be able to represent a complex query
or to use any database-specific features it's fairly convenient for doing the
simple CRUD stuff. And for advanced queries the underlying driver is always
exposed as a `*sql.DB` or a `*mgo.Session` so you can still be able to use
any database-pro spells.
One of the features you may find useful is the ability of `gosexy/db` to make
relations between different databases that talk different protocols with ease:
```
items, err := peopleCollection.FindAll(
db.RelateAll{
"works": db.On{
worksCollection,
db.Cond{"author_id": "{id}"},
},
},
)
```
In the above example, `peopleCollection` and `worksCollection` are
`db.Collection` objects and they could be collections or tables of any of the
supported databases. You can even relate NoSQL collections to SQL tables!
`gosexy/db` is a work in progress but its core features are ready for use.
## Installation ## Installation
Use `go get` to download and install `gosexy/db`. Use `go get` to download and install `gosexy/db`.
```sh ```sh
# Getting gosexy/db go get github.com/gosexy/db
$ go get github.com/gosexy/db
``` ```
The `gosexy/db` package provides shared interfaces and datatypes only, in order to connect to an actual database The `gosexy/db` package provides shared interfaces and datatypes only, it can't
a wrapper is required. connect to any database by itself, in order to connect to an actual database
a database wrapper is required.
## Database wrappers
Database wrappers may have special installation requirements, please refer to
the appropriate documentation reference on the following list.
* [mongo](http://gosexy.org/db/wrappers/mongo)
* [mysql](http://gosexy.org/db/wrappers/mysql)
* [postgresql](http://gosexy.org/db/wrappers/postgresql)
* [sqlite](http://gosexy.org/db/wrappers/sqlite)
## Usage example ## Usage example
Let's suppose we want to use the `mongo` driver for [MongoDB][1]. Let's suppose we want to use the "mongo" wrapper for [MongoDB][1].
Use `go get` to retrieve and install the "mongo" wrapper.
```sh ```sh
# Installing the driver go get github.com/gosexy/db/mongo
$ go get github.com/gosexy/db/mongo
``` ```
Once the driver is installed, import it into your project. Import `gosexy/db` and the wrapper into your project.
```go ```go
// Importing driver and abstraction layer
import ( import (
"github.com/gosexy/db" "github.com/gosexy/db"
/* Import the driver to the blank namespace */ // The wrapper goes to the blank namespace.
_ "github.com/gosexy/db/mongo" _ "github.com/gosexy/db/mongo"
) )
``` ```
Set up a variable to hold your database connection credentials. Set up a variable to configure your database connection.
```go ```go
settings := db.DataSource{ var settings = db.DataSource{
Host: "localhost", Host: "localhost",
Database: "dbname", Database: "dbname",
User: "myusername", User: "myusername",
...@@ -53,18 +106,20 @@ settings := db.DataSource{ ...@@ -53,18 +106,20 @@ settings := db.DataSource{
} }
``` ```
Then use `db.Open` to connect to the database you've just set up. Use `db.Open` to connect to the database you've just set up.
```go ```go
// Connect using the mongo driver. // Connect using the mongo driver.
sess, err := db.Open("mongo", settings) sess, err := db.Open("mongo", settings)
if err != nil { if err != nil {
panic(err) panic(err)
} }
defer sess.Close() defer sess.Close()
``` ```
Now you can query the database. Insert some items and retrieve rows.
```go ```go
animals, _ := sess.Collection("animals") animals, _ := sess.Collection("animals")
...@@ -100,85 +155,15 @@ for _, item := range items { ...@@ -100,85 +155,15 @@ for _, item := range items {
} }
``` ```
The same example goes for other drivers with few modifications, just change the driver name to The same example goes for other wrappers, you just change the driver name to
`mysql`, `postgresql` or `sqlite`. Please consider that SQL databases do not accept datatypes like `mysql`, `postgresql` or `sqlite`.
`sugar.List{}` and that they expect an existing table.
### Full example
```go
// _examples/mongo.go
package main
import (
"fmt"
"github.com/gosexy/db"
_ "github.com/gosexy/db/mongo"
"github.com/gosexy/sugar"
)
const host = "debian"
const dbname = "dev"
func main() {
sess, err := db.Open("mongo", db.DataSource{Host: host, Database: dbname})
if err != nil {
panic(err)
}
defer sess.Close()
sess.Drop()
animals, _ := sess.Collection("animals")
animals.Append(db.Item{
"animal": "Bird",
"young": "Chick",
"female": "Hen",
"male": "Cock",
"group": "flock",
})
animals.Append(db.Item{
"animal": "Bovidae",
"young": "Calf",
"female": "Cow",
"male": "Bull",
"group": "Herd",
})
animals.Append(db.Item{
"animal": "Canidae",
"young": sugar.List{"Puppy", "Pup"},
"female": "Bitch",
"male": "Dog",
"group": "Pack",
})
items := animals.FindAll()
for _, item := range items {
fmt.Printf("animal: %s, young: %s\n", item["animal"], item["young"])
}
}
```
## Documentation ## Documentation
There is an [online reference](http://gosexy.org/db). If you're in trouble, you may want to try the
[online reference](http://gosexy.org/db) and the [documentation page][5].
You can also read `gosexy/db` documentation from a terminal.
```sh Speak IRC? you can contact [the author][6] at #menteslibres on freenode.
# Reading gosexy/db docs.
$ go doc github.com/gosexy/db
# Reading driver docs.
$ go doc github.com/gosexy/db
```
## Things to do ## Things to do
...@@ -190,10 +175,24 @@ This is an evolving project, there are still some things to do: ...@@ -190,10 +175,24 @@ This is an evolving project, there are still some things to do:
## Changelog ## Changelog
2013/03/10 - Breaking change: Find() and FindAll() now will return ([item],
error).
- Adding db.Result and methods for iterating over results.
- Adding the ability to use struct{} for fetching and inserting
rows.
- Adding helper package gosexy/db/util for internal usage.
2012/12/02 - Changing db.Table.Collection and adding db.Open(). 2012/12/02 - Changing db.Table.Collection and adding db.Open().
2012/09/21 - Changing some methods parameters and return values, improving error handling and testing many data types. 2012/09/21 - Changing some methods parameters and return values, improving
2012/08/29 - Created the main site docs and moved the repo to "http://github.com/gosexy". error handling and testing many data types.
2012/07/23 - Splitted database wrappers into packages. Changed ``db.Where`` to ``db.Cond``. 2012/08/29 - Created the main site docs and moved the repo to
"http://github.com/gosexy".
2012/07/23 - Splitted database wrappers into packages. Changed db.Where to
db.Cond.
2012/07/09 - First public beta with MySQL, MongoDB, PostgreSQL and SQLite3. 2012/07/09 - First public beta with MySQL, MongoDB, PostgreSQL and SQLite3.
[1]: http://mongodb.org [1]: http://mongodb.org
[2]: http://mysql.com
[3]: http://postgresql.org
[4]: http://sqlite.com
[5]: http://godoc.org/github.com/gosexy/db
[6]: http://xiam.menteslibres.org
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment