From cefb20d12fc1f02bf50f7cde7130995b71e9cc0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Nieto?= <xiam@menteslibres.org>
Date: Wed, 29 Aug 2012 06:20:42 -0500
Subject: [PATCH] Updating README.md files.
---
README.md | 221 +++++--------------------------------------
mongo/README.md | 38 +-------
mysql/README.md | 37 +-------
postgresql/README.md | 22 +----
sqlite/README.md | 40 +-------
5 files changed, 29 insertions(+), 329 deletions(-)
diff --git a/README.md b/README.md
index f7f96580..81ff0038 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,9 @@
# gosexy/db
-This package is a wrapper of many third party database drivers. The goal of this abstraction is to provide a common, simplified, consistent layer for working with different databases without the need of SQL statements.
+This package is a wrapper of many third party database drivers. The goal of this abstraction is to provide a common,
+simplified, consistent layer for working with different databases without the need of SQL statements.
+
+You can read our online documentation at [gosexy.org](http://gosexy.org).
## Installation
@@ -8,16 +11,18 @@ Use ``go get`` to download and install ``gosexy/db``.
$ go get github.com/gosexy/db
-This package provides shared interfaces and datatypes only, in order to connect to an actual database a driver is required.
-
-Please refer to the database driver documentation to learn how to install a specific driver.
+This package provides shared interfaces and datatypes only, in order to connect to an actual database a wrapper is required.
## Available drivers
-* [mongo](/xiam/gosexy/tree/master/db/mongo)
-* [mysql](/xiam/gosexy/tree/master/db/mysql)
-* [postgresql](/xiam/gosexy/tree/master/db/postgresql)
-* [sqlite](/xiam/gosexy/tree/master/db/sqlite)
+* [mongo](/gosexy/db/tree/master/mongo)
+* [mysql](/gosexy/db/tree/master/mysql)
+* [postgresql](/gosexy/db/tree/master/postgresql)
+* [sqlite](/gosexy/db/tree/master/sqlite)
+
+## Connecting to a database
+
+You may want to read a more descriptive reference on [how to connect](http://gosexy.org/db) to databases using ``gosexy/db``.
### Importing the database
@@ -27,7 +32,8 @@ Once you've installed a driver, you need to import it into your Go code:
### Setting up a database source
-We are going to use the [mysql](/xiam/gosexy/tree/master/db/mysql) driver in our examples. If you want to use another driver (such as ``mongo``) just replace ``mysql`` with the name of your driver and everything should work the same.
+We are going to use the [mysql](/gosexy/db/tree/master/mysql) driver in our examples. If you want to use another driver
+(such as ``mongo``) just replace ``mysql`` with the name of your driver and everything should work the same.
sess := mysql.Session(db.DataSource{Host: "localhost", Database: "test", User: "myuser", Password: "mypass"})
@@ -48,202 +54,24 @@ Use your recently configured ``db.Database`` to request the driver to actually c
// Setting up database.
sess := mysql.Session(db.DataSource{Host: "localhost", Database: "test", User: "myuser", Password: "mypass"})
- sess.Open()
+ err := sess.Open()
// Don't forget to close the connection when it's not required anymore.
- defer sess.Close()
-
-### db.Database methods
-
-The ``db.Database`` interface exposes the very same methods for all databases.
-
- // Database methods.
- type Database interface {
- Driver() interface{}
-
- Open() error
- Close() error
-
- Collection(string) Collection
- Collections() []string
-
- Use(string) error
- Drop() error
- }
-
-#### db.Database.Driver() interface{}
-
-Returns the raw driver as an ``interface{}``, for example, if you're using ``mongo.Session`` it will return an interface to ``*mgo.Session``, and if you're using ``mysql.Session`` it will return an interface to ``*sql.DB``, this is the only method that may return different data structures on different databases.
-
-#### db.Database.Open() error
-
-Requests a connection to the database session. Returns an error if something goes wrong.
-
-#### db.Database.Close() error
-
-Disconnects from the database session. Returns an error if something goes wrong.
-
-#### db.Database.Collection(name string) Collection
-
-Returns a ``db.Collection`` object from the current database given the name, collections are sets of rows or documents, this could be a MongoDB collection or a MySQL/PostgreSQL/SQLite table. You can create, read, update or delete rows from a collection. Please read all the methods avaiable for ``db.Collection`` further into this manual.
-
-#### db.Database.Collections() []string
-
-Returns the names of all the collections in the current database.
-
-#### db.Database.Use(name string) error
-
-Makes the session switch between databases given the name. Returns an error if it fails.
-
-#### db.Database.Drop() error
-
-Erases the entire database and all the collections. Returns an error if it fails.
-
-### db.Collection methods
-
-Collections are sets of rows or documents, this could be a MongoDB collection or a MySQL/PostgreSQL/SQLite table. You can create, read, update or delete rows from a collection.
-
-When you request data from a Collection with ``db.Collection.Find()`` or ``db.Collection.FindAll()``, a special object with structure ``db.Item`` is returned.
-
- // Collection methods.
- type Collection interface {
- Append(...interface{}) bool
-
- Count(...interface{}) int
-
- Find(...interface{}) Item
- FindAll(...interface{}) []Item
-
- Update(...interface{}) bool
-
- Remove(...interface{}) bool
-
- Truncate() bool
+ if err == nil {
+ defer sess.Close()
}
- // Rows from a result.
- type Item map[string]interface{}
-
-#### db.Collection.Append(...interface{}) bool
-
-Appends one or more items to the collection.
-
- collection.Append(db.Item { "name": "Peter" })
-
-#### db.Collection.Count(...interface{}) int
-
-Returns the number of total items matching the provided conditions.
-
- total := collection.Count(db.Cond { "name": "Peter" })
-
-#### db.Collection.Find(...interface{}) db.Item
-
-Return the first Item of the collection that matches all the provided conditions. Ordering of the conditions does not matter, but you must take in account that they are evaluated from left to right and from top to bottom.
-
- // The following statement is equivalent to WHERE name = "John" AND last_name = "Doe" AND (age = 15 OR age = 20)
- collection.Find(
- db.Cond { "name": "John" },
- db.Cond { "last_name": "Doe" },
- db.Or {
- db.Cond { "age": 15 },
- db.Cond { "age": 20 },
- },
- )
-
-You can also use relations in your definition
-
- collection.FindAll(
- // One-to-one relation with the table "places".
- db.Relate{
- "lives_in": db.On{
- session.Collection("places"),
- // Relates rows of the table "places" where place.code_id = collection.place_code_id.
- db.Cond{"code_id": "{place_code_id}"},
- },
- },
- db.RelateAll{
- // One-to-many relation with the table "children".
- "has_children": db.On{
- session.Collection("children"),
- // Relates rows of the table "children" where children.parent_id = collection.id
- db.Cond{"parent_id": "{id}"},
- },
- // One-to-many relation with the table "visits".
- "has_visited": db.On{
- session.Collection("visits"),
- // Relates rows of the table "visits" where visits.person_id = collection.id
- db.Cond{"person_id": "{id}"},
- // A nested relation
- db.Relate{
- // Relates rows of the table "places" with the "visits" table.
- "place": db.On{
- session.Collection("places"),
- // Cond places.id = visits.place_id
- db.Cond{"id": "{place_id}"},
- },
- },
- },
- },
- )
-
-#### db.Collection.FindAll(...interface{}) []db.Item
-
-Returns all the Items (``[]db.Item``) of the collection that match all the provided conditions. See ``db.Collection.Find()``.
-
-Be aware that there are some extra parameters that you can pass to ``db.Collection.FindAll()`` but not to ``db.Collection.Find()``, like ``db.Limit(n)`` or ``db.Offset(n)``.
-
- // Just give me the the first 10 rows with last_name = "Smith"
- collection.Find(
- db.Cond { "last_name": "Smith" },
- db.Limit(10),
- )
-
-#### db.Collection.Update(...interface{}) bool
-
-Updates all the items of the collection that match all the provided conditions. You can specify the modification type by using ``db.Set``, ``db.Modify`` or ``db.Upsert``. At the time of this writing ``db.Modify`` and ``db.Upsert`` are only available for ``mongo.Session``.
-
- // Example of assigning field values with Set:
- collection.Update(
- db.Cond { "name": "José" },
- db.Set { "name": "Joseph"},
- )
-
- // Example of custom modification with db.Modify (for mongo.Session):
- collection.Update(
- db.Cond { "times <": "10" },
- db.Modify { "$inc": { "times": 1 } },
- )
-
- // Example of inserting if none matches with db.Upsert (for mongo.Session):
- collection.Update(
- db.Cond { "name": "Roberto" },
- db.Upsert { "name": "Robert"},
- )
-
-#### db.Collection.Remove(...interface{}) bool
-
-Deletes all the items of the collection that match the provided conditions.
-
- collection.Remove(
- db.Cond { "name": "Peter" },
- db.Cond { "last_name": "Parker" },
- )
-
-#### db.Collection.Truncate() bool
-
-Deletes the whole collection.
-
- collection.Truncate()
-
## Documentation
-You can read ``gosexy/db`` documentation from a terminal
+Please read the [online reference](http://gosexy.org/db) on ``gosexy/db``.
+
+You can also read ``gosexy/db`` documentation from a terminal
$ go doc github.com/gosexy/db
-Or you can [browse it](http://go.pkgdoc.org/github.com/gosexy/db) online.
+## Things to do
-## TO-DO
+This is an evolving project, so there is a lot of work to do:
* Add db.Upsert and db.Modify for SQL databases.
* Add Go time datatype.
@@ -253,5 +81,6 @@ Or you can [browse it](http://go.pkgdoc.org/github.com/gosexy/db) online.
## Changelog
- 2012/07/23 - Splitted database wrappers into packages. Changed ``Where`` to ``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.
diff --git a/mongo/README.md b/mongo/README.md
index aaea2ee1..53ab2c64 100644
--- a/mongo/README.md
+++ b/mongo/README.md
@@ -1,39 +1,3 @@
# gosexy/db/mongo
-This driver is a wrapper of [mgo](http://labix.org/mgo)
-
-## Requirements
-
-The [bazaar](http://bazaar.canonical.com/en/) version control system is required by ``mgo``.
-
-If you're using ``brew`` and OSX, you can install it like this
-
- $ brew install bzr
-
-On ArchLinux you could use
-
- $ sudo pacman -S bzr
-
-And on Debian based distros
-
- $ sudo aptitude install bzr
-
-## Installation
-
- $ go get github.com/gosexy/db/mongo
-
-## Usage
-
- import (
- "github.com/gosexy/db"
- "github.com/gosexy/db/mongo"
- )
-
-## Connecting to a MongoDB database
-
- sess := mongo.Session(db.DataSource{Host: "127.0.0.1"})
-
- err := sess.Open()
- defer sess.Close()
-
-Read full documentation and examples on the [gosexy/db](/xiam/gosexy/tree/master/db) manual.
+Please read the full docs, acknowledgements and examples at [http://gosexy.org/db/wrappers/mongo](http://gosexy.org/db/wrappers/mongo).
diff --git a/mysql/README.md b/mysql/README.md
index aededdec..e85846f8 100644
--- a/mysql/README.md
+++ b/mysql/README.md
@@ -1,39 +1,4 @@
# gosexy/db/mysql
-This driver is a wrapper of [go-mysql-driver](http://code.google.com/p/go-mysql-driver/)
+Please read the full docs, acknowledgements and examples at [http://gosexy.org/db/wrappers/mysql](http://gosexy.org/db/wrappers/mysql).
-## Requirements
-
-The [mercurial](http://mercurial.selenic.com/) version control system is required by ``go-mysql-driver``.
-
-If you're using ``brew`` and OSX, you can install it like this
-
- $ brew install hg
-
-On ArchLinux you could use
-
- $ sudo pacman -S mercurial
-
-And on Debian based distros
-
- $ sudo aptitude install mercurial
-
-## Installation
-
- $ go get github.com/gosexy/db/mysql
-
-## Usage
-
- import (
- "github.com/gosexy/db"
- "github.com/gosexy/db/mysql"
- )
-
-## Connecting to a MySQL database
-
- sess := mysql.Session(db.DataSource{Host: "127.0.0.1"})
-
- err := sess.Open()
- defer sess.Close()
-
-Read full documentation and examples on the [gosexy/db](/xiam/gosexy/tree/master/db) manual.
diff --git a/postgresql/README.md b/postgresql/README.md
index 32c23cb2..79493c06 100644
--- a/postgresql/README.md
+++ b/postgresql/README.md
@@ -1,23 +1,3 @@
# gosexy/db/postgresql
-This driver is a wrapper of [pq](https://github.com/bmizerany/pq). In order to work with ``gosexy/db`` the original driver had to be [forked](https://github.com/xiam/gopostgresql) as the changes made to it are incompatible with some of pq's own features.
-
-## Installation
-
- $ go get github.com/gosexy/db/postgresql
-
-## Usage
-
- import (
- "github.com/gosexy/db"
- "github.com/gosexy/db/postgresql"
- )
-
-## Connecting to a PostgreSQL database
-
- sess := postgresql.Session(db.DataSource{Host: "127.0.0.1"})
-
- err := sess.Open()
- defer sess.Close()
-
-Read full documentation and examples on the [gosexy/db](/xiam/gosexy/tree/master/db) manual.
+Please read the full docs, acknowledgements and examples at [http://gosexy.org/db/wrappers/postgresql](http://gosexy.org/db/wrappers/postgresql).
diff --git a/sqlite/README.md b/sqlite/README.md
index 76739a4e..2b7515b6 100644
--- a/sqlite/README.md
+++ b/sqlite/README.md
@@ -1,42 +1,4 @@
# gosexy/db/sqlite
-This driver is a wrapper of [sqlite3](https://github.com/mattn/go-sqlite3). In order to work with ``gosexy/db`` the original driver had to be [forked](https://github.com/xiam/gosqlite3) as the changes made to it are incompatible with some of sqlite3's own features.
+Please read the full docs, acknowledgements and examples at [http://gosexy.org/db/wrappers/sqlite](http://gosexy.org/db/wrappers/sqlite).
-## Requirements
-
-The sqlite3 driver uses cgo, and it requires ``pkg-config`` and the sqlite3 header files in order to be installed.
-
-If you're using ``brew`` and OSX, you can install them like this
-
- $ brew install pkg-config
- $ brew install sqlite3
-
-On ArchLinux you could use
-
- $ sudo pacman -S pkg-config
- $ sudo pacman -S sqlite3
-
-And on Debian based distros
-
- $ sudo aptitude install pkg-config
- $ sudo aptitude install libsqlite3-dev
-
-## Installation
-
- $ go get github.com/gosexy/db/sqlite
-
-## Usage
-
- import (
- "github.com/gosexy/db"
- "github.com/gosexy/db/sqlite"
- )
-
-## Connecting to a SQLite3 database
-
- sess := sqlite.Session(db.DataSource{Database: "/path/to/sqlite3.db"})
-
- err := sess.Open()
- defer sess.Close()
-
-Read full documentation and examples on the [gosexy/db](/xiam/gosexy/tree/master/db) manual.
--
GitLab