Key concepts

Through this documentation you'll find a few special concepts, the most important are the ones defined below:

session: a representation of an established connection with a database.

collection: a set of items that belong to a concrete SQL table or a NoSQL collection.

The term 'collection' is used indistinctively by methods that work on both SQL and NoSQL databases.

result set: a subset of items in a collection that match specific conditions. It is retrieved with Find(). The whole result set can be delimited or modified through different methods, like Update(), Delete(), Insert(), All(), or One().

The figure below ilustrates the session, collection, and result-set concepts:

session collections and results

General considerations

In order to use upper/db efficiently, it is advisable that you:

  1. Understand the database you're working with (relational or document-oriented)
  2. Use Go structs to describe data models. One struct per collection is a good practice.
  3. Try to use db.Collection methods applicable to both SQL and NoSQL first.
  4. Use the SQL builder or raw SQL only when needed.