/README.md

http://github.com/sdegutis/GoRM · Markdown · 80 lines · 49 code · 31 blank · 0 comment · 0 complexity · f190f98a628eda8f6230240f950db5f0 MD5 · raw file

  1. ## GoRM
  2. GoRM 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.
  3. ### How do we use it?
  4. Open a database
  5. db, _ := OpenDB("test.db")
  6. db.Close() // you'll probably wanna close it at some point
  7. Model a struct after a table in the db
  8. type Person struct {
  9. Id int
  10. Name string
  11. Age int
  12. }
  13. Create an object and save it
  14. var someone Person
  15. someone.Name = "john"
  16. someone.Age = 20
  17. db.Save(&someone)
  18. Fetch a single object
  19. var person1 Person
  20. db.Get(&person1, "id = ?", 3)
  21. var person2 Person
  22. db.Get(&person2, 3) // this is shorthand for the version above
  23. var person3 Person
  24. db.Get(&person3, "name = ?", "john") // more complex query
  25. var person4 Person
  26. db.Get(&person4, "name = ? and age < ?", "john", 88) // even more complex
  27. Fetch multiple objects
  28. var bobs []Person
  29. err := db.GetAll(&bobs, "name = ?", "bob")
  30. var everyone []Person
  31. err := db.GetAll(&everyone, "") // use empty string to omit "where" clause
  32. Saving new and existing objects
  33. person2.Name = "Jack" // an already-existing person in the database, from the example above
  34. db.Save(&person2)
  35. var newGuy Person
  36. newGuy.Name = "that new guy"
  37. newGuy.Age = 27
  38. db.Save(&newGuy)
  39. // newGuy.Id is suddenly valid, and he's in the database now.
  40. ### Installing GoRM
  41. Obviously [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).
  42. This 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.
  43. ### Known bugs
  44. Right 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.
  45. Also, at the moment, relationship-support is in the works, but not yet implemented.
  46. All in all, it's not entirely ready for advanced use yet, but it's getting there.
  47. ### Etc
  48. The 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.
  49. Feel free to send pull requests with cool features added :)