/README.md

 1## GoRM
 2
 3GoRM is an ORM for Go. It lets you map Go `struct`s to tables in a database. It's intended to be very lightweight, doing very little beyond what you really want. For example, when fetching data, instead of re-inventing a query syntax, we just delegate your query to the underlying database, so you can write the "where" clause of your SQL statements directly. This allows you to have more flexibility while giving you a convenience layer. But GoRM also has some smart defaults, for those times when complex queries aren't necessary.
 4
 5### How do we use it?
 6
 7Open a database
 8
 9	db, _ := OpenDB("test.db")
10	db.Close() // you'll probably wanna close it at some point
11
12Model a struct after a table in the db
13
14	type Person struct {
15		Id int
16		Name string
17		Age int
18	}
19
20Create an object and save it
21
22	var someone Person
23	someone.Name = "john"
24	someone.Age = 20
25	
26	db.Save(&someone)
27
28Fetch a single object
29
30	var person1 Person
31	db.Get(&person1, "id = ?", 3)
32
33	var person2 Person
34	db.Get(&person2, 3) // this is shorthand for the version above
35	
36	var person3 Person
37	db.Get(&person3, "name = ?", "john") // more complex query
38	
39	var person4 Person
40	db.Get(&person4, "name = ? and age < ?", "john", 88) // even more complex
41
42Fetch multiple objects
43
44	var bobs []Person
45	err := db.GetAll(&bobs, "name = ?", "bob")
46
47	var everyone []Person
48	err := db.GetAll(&everyone, "") // use empty string to omit "where" clause
49
50Saving new and existing objects
51
52	person2.Name = "Jack" // an already-existing person in the database, from the example above
53	db.Save(&person2)
54	
55	var newGuy Person
56	newGuy.Name = "that new guy"
57	newGuy.Age = 27
58	
59	db.Save(&newGuy)
60	// newGuy.Id is suddenly valid, and he's in the database now.
61
62### Installing GoRM
63
64Obviously [Go](http://golang.org/) should be installed. [The official installation directions](http://golang.org/doc/install.html) are recommended, rather than installing it through a package (such as homebrew).
65
66This package also requires [my version of the `sqlite` package](https://github.com/sdegutis/sqlite-go-wrapper). Clone it, then run `make install` and you'll be all set.
67
68### Known bugs
69
70Right now, it only interfaces with SQLite. The goal however is to add support for other databases in the future, including maybe PostgreSQL and CouchDB or NoSQL? Who knows.
71
72Also, at the moment, relationship-support is in the works, but not yet implemented.
73
74All in all, it's not entirely ready for advanced use yet, but it's getting there.
75
76### Etc
77
78The idea came about in #go-nuts on irc.freenode.net... Namegduf and wrtp were instrumental in helping solidify the main principles, and I think wrtp came up with the name.
79
80Feel free to send pull requests with cool features added :)