Kallax is a PostgreSQL typesafe ORM for the Go language.

It aims to provide a way of programmatically write queries and interact with a PostgreSQL database without having to write a single line of SQL, use strings to refer to columns and use values of any type in queries.

For that reason, the first priority of kallax is to provide type safety to the data access layer.Another of the goals of kallax is make sure all models are, first and foremost, Go structs without having to use database-specific types such as, for example,sql.NullInt64.Support for arrays of all basic Go types and all JSON and arrays operators is provided as well.

Contents

• Installation
• Usage
• Define models
  • Struct tags
  • Primary keys
  • Model constructors
  • Model events
• Model schema
  • Use schema
• Manipulate models
  • Insert models
  • Update models
  • Save models
  • Delete models
• Query models
  • Simple queries
  • Generated findbys
  • Query with relationships
  • Querying JSON
• Transactions
• Caveats
• Migrations
• Custom operators
• Debug SQL queries
• Benchmarks
• Acknowledgements
• Contributing

Installation

The recommended way to installkallax is:

go get -u gopkg.in/src-d/go-kallax.v1/...

kallax includes a binary tool used bygo generate,please be sure that$GOPATH/bin is on your$PATH

Usage

Imagine you have the following file in the package where your models are.

package modelstype User struct {        kallax.Model         `table:"users" pk:"id"`        ID       kallax.ULID        Username string        Email    string        Password string}

Then put the following on any file of that package:

//go:generate kallax gen

Now all you have to do is rungo generate ./... and akallax.go file will be generated with all the generated code for your model.

If you don't want to usego generate, even though is the preferred use, you can just go to your package and runkallax gen yourself.

Excluding files from generation

Sometimes you might want to use the generated code in the same package it is defined and cause problems during the generation when you regenerate your models. You can exclude files in the package by changing thego:generate comment to the following:

//go:generate kallax gen -e file1.go -e file2.go

Define models

A model is just a Go struct that embeds thekallax.Model type. All the fields of this struct will be columns in the database table.

A model also needs to have one (and just one) primary key. The primary key is defined using thepk struct tag on thekallax.Model embedding. You can also set the primary key in a field of the struct with the struct tagpk, which can bepk:"" for a non auto-incrementable primary key orpk:"autoincr" for one that is auto-incrementable.More about primary keys is discussed at theprimary keys section.

First, let's review the rules and conventions for model fields:

• All the fields with basic types or types that implementsql.Scanner anddriver.Valuer will be considered a column in the table of their matching type.
• Arrays or slices of types mentioned above will be treated as PostgreSQL arrays of their matching type.
• Fields that are structs (or pointers to structs) or interfaces not implementingsql.Scanner anddriver.Valuer will be considered as JSON. Same with arrays or slices of types that follow these rules.
• Fields that are structs (or pointers to structs) with the struct tagkallax:",inline" or are embedded will be considered inline, and their fields would be considered as if they were at the root of the model.
• All pointer fields are nullable by default. That means you do not need to usesql.NullInt64,sql.NullBool and the likes because kallax automatically takes care of that for you.WARNING: all JSON andsql.Scanner implementors will be initialized withnew(T) in case they arenil before they are scanned.
• By default, the name of a column will be the name of the struct field converted to lower snake case (e.g.UserName =>user_name,UserID =>user_id). You can override it with the struct tagkallax:"my_custom_name".
• Slices of structs (or pointers to structs) that are models themselves will be considered a 1:N relationship. Arrays of models arenot supported by design.
• A struct or pointer to struct field that is a model itself will be considered a 1:1 relationship.
• For relationships, the foreign key is assumed to be the name of the model converted to lower snake case plus_id (e.g.User =>user_id). You can override this with the struct tagfk:"my_custom_fk".
• For inverse relationship, you need to use the struct tagfk:",inverse". You can combine theinverse with overriding the foreign key withfk:"my_custom_fk,inverse". In the case of inverses, the foreign key name does not specify the name of the column in the relationship table, but the name of the column in the own table. The name of the column in the other table is always the primary key of the other model and cannot be changed for the time being.
• Foreign keysdo not have to be in the model, they are automagically managed underneath by kallax.

Kallax also provides akallax.Timestamps struct that containsCreatedAt andUpdatedAt that will be managed automatically.

Let's see an example of models with all these cases:

type User struct {        kallax.Model       `table:"users" pk:"id,autoincr"`        kallax.Timestamps        ID        int64        Username  string        Password  string        Emails    []string        // This is for demo purposes, please don't do this        // 1:N relationships load all N rows by default, so        // only do it when N is small.        // If N is big, you should probably be querying the posts        // table instead.        Posts []*Post `fk:"poster_id"`}type Post struct {        kallax.Model      `table:"posts"`        kallax.Timestamps        ID       int64    `pk:"autoincr"`        Content  string   `kallax:"post_content"`        Poster   *User    `fk:"poster_id,inverse"`        Metadata Metadata `kallax:",inline"`}type Metadata struct {        MetadataType MetadataType        Metadata map[string]interface{} // this will be json}

Struct tags

Primary keys

Primary key types need to satisfy theIdentifier interface. Even though they have to do that, the generator is smart enough to know when to wrap some types to make it easier on the user.

The following types can be used as primary key:

• int64
• uuid.UUID
• kallax.ULID: this is a type kallax provides that implements a lexically sortable UUID. You can store it asuuid like any other UUID, but internally it's an ULID and you will be able to sort lexically by it.

Due to how sql mapping works, pointers touuid.UUID andkallax.ULID are not set tonil if they appear asNULL in the database, but touuid.Nil. Using pointers to UUIDs is discouraged for this reason.

If you need another type as primary key, feel free to open a pull request implementing that.

Known limitations

• Only one primary key can be specified and it can't be a composite key.

Model constructors

Kallax generates a constructor for your type namedNew{TypeName}. But you can customize it by implementing a private constructor namednew{TypeName}. The constructor generated by kallax will use the same signature your private constructor has. You can use this to provide default values or construct the model with some values.

If you implement this constructor:

func newUser(username, password string, emails ...string) (*User, error) {        if username != "" || len(emails) == 0 || password != "" {                return errors.New("all fields are required")        }        return &User{Username: username, Password: password, Emails: emails}}

Kallax will generate one with the following signature:

func NewUser(username string, password string, emails ...string) (*User, error)

IMPORTANT: if your primary key is not auto-incrementable, you should set an ID for every model you create in your constructor. Or, at least, set it before saving it. Inserting, updating, deleting or reloading an object with no primary key set will return an error.

If you don't implement your own constructor it's ok, kallax will generate one for you just instantiating your object like this:

func NewT() *T {        return new(T)}

Model events

Events can be defined for models and they will be invoked at certain times of the model lifecycle.

• BeforeInsert: will be called before inserting the model.
• BeforeUpdate: will be called before updating the model.
• BeforeSave: will be called before updating or inserting the model. It's always called beforeBeforeInsert andBeforeUpdate.
• BeforeDelete: will be called before deleting the model.
• AfterInsert: will be called after inserting the model. The presence of this event will cause the insertion of the model to run in a transaction. If the event returns an error, it will be rolled back.
• AfterUpdate: will be called after updating the model. The presence of this event will cause the update of the model to run in a transaction. If the event returns an error, it will be rolled back.
• AfterSave: will be called after updating or inserting the model. It's always called afterAfterInsert andAfterUpdate. The presence of this event will cause the operation with the model to run in a transaction. If the event returns an error, it will be rolled back.
• AfterDelete: will be called after deleting the model. The presence of this event will cause the deletion to run in a transaction. If the event returns an error, it will be rolled back.

To implement these events, just implement the following interfaces. You can implement as many as you want:

• BeforeInserter
• BeforeUpdater
• BeforeSaver
• BeforeDeleter
• AfterInserter
• AfterUpdater
• AfterSaver
• AfterDeleter

Example:

func (u *User) BeforeSave() error {        if u.Password == "" {                return errors.New("cannot save user without password")        }        if !isCrypted(u.Password) {                u.Password = crypt(u.Password)        }        return nil}

Kallax generated code

Kallax generates a bunch of code for every single model you have and saves it to a file namedkallax.go in the same package.

For every model you have, kallax will generate the following for you:

• Internal methods for your model to make it work with kallax and satisfy theRecord interface.
• A store named{TypeName}Store: the store is the way to access the data. A store of a given type is the way to access and manipulate data of that type. You can get an instance of the type store withNew{TypeName}Store(*sql.DB).
• A query named{TypeName}Query: the query is the way you will be able to build programmatically the queries to perform on the store. A store only will accept queries of its own type. You can create a new query withNew{TypeName}Query().The query will contain methods for adding criteria to your query for every field of your struct, calledFindBys. The query object is not immutable, that is, every condition added to it, changes the query. If you want to reuse part of a query, you can call theCopy() method of a query, which will return a query identical to the one used to call the method.
• A resultset named{TypeName}ResultSet: a resultset is the way to iterate over and obtain all elements in a resultset returned by the store. A store of a given type will always return a result set of the matching type, which will only return records of that type.
• Schema of all the models containing all the fields. That way, you can access the name of a specific field without having to use a string, that is, a typesafe way.

Model schema

Use schema

A global variableSchema will be created in yourkallax.go, that contains a field with the name of every of your models. Those are the schemas of your models. Each model schema contains all the fields of that model.

So, to access the username field of the user model, it can be accessed as:

Schema.User.Username

Manipulate models

For all of the following sections, we will assume we have a storestore for our model's type.

Insert models

To insert a model we just need to use theInsert method of the store and pass it a model. If the primary key is not auto-incrementable and the object does not have one set, the insertion will fail.

user := NewUser("fancy_username", "super_secret_password", "foo@email.me")err := store.Insert(user)if err != nil {        // handle error}

If our model has relationships, they will be saved, and so will the relationships of the relationships and so on. TL;DR: inserts are recursive.Note: the relationships will be saved usingSave, notInsert.

user := NewUser("foo")user.Posts = append(user.Posts, NewPost(user, "new post"))err := store.Insert(user)if err != nil {        // handle error}

If there are any relationships in the model, both the model and the relationships will be saved in a transaction and only succeed if all of them are saved correctly.

Update models

To insert a model we just need to use theUpdate method of the store and pass it a model. It will return an error if the model was not already persisted or has not an ID.

user := FindLast()rowsUpdated, err := store.Update(user)if err != nil {        // handle error}

By default, when a model is updated, all its fields are updated. You can also specify which fields to update passing them to update.

rowsUpdated, err := store.Update(user, Schema.User.Username, Schema.User.Password)if err != nil {        // handle error}

If our model has relationships, they will be saved, and so will the relationships of the relationships and so on. TL;DR: updates are recursive.Note: the relationships will be saved usingSave, notUpdate.

user := FindLastPoster()rowsUpdated, err := store.Update(user)if err != nil {        // handle error}

If there are any relationships in the model, both the model and the relationships will be saved in a transaction and only succeed if all of them are saved correctly.

Save models

To save a model we just need to use theSave method of the store and pass it a model.Save is just a shorthand that will callInsert if the model is not yet persisted andUpdate if it is.

updated, err := store.Save(user)if err != nil {        // handle error}if updated {        // it was updated, not inserted}

If our model has relationships, they will be saved, and so will the relationships of the relationships and so on. TL;DR: saves are recursive.

user := NewUser("foo")user.Posts = append(user.Posts, NewPost(user, "new post"))updated, err := store.Save(user)if err != nil {        // handle error}

If there are any relationships in the model, both the model and the relationships will be saved in a transaction and only succeed if all of them are saved correctly.

Delete models

To delete a model we just have to use theDelete method of the store. It will return an error if the model was not already persisted.

err := store.Delete(user)if err != nil {        // handle error}

Relationships of the model arenot automatically removed usingDelete.

For that, specific methods are generated in the store of the model.

For one to many relationships:

// remove specific postserr := store.RemovePosts(user, post1, post2, post3)if err != nil {        // handle error}// remove all postserr := store.RemovePosts(user)

For one to one relationships:

// remove the thingerr := store.RemoveThing(user)

Note that for that to work, the thing you're deleting mustnot be empty. That is, you need to eagerly load (or set afterwards) the relationships.

user, err := store.FindOne(NewUserQuery())checkErr(err)// THIS WON'T WORK! We've not loaded "Things"err := store.RemoveThings(user)user, err := store.FindOne(NewUserQuery().WithThings())checkErr(err)// THIS WILL WORK!err := store.RemoveThings(user)

Query models

Simple queries

To perform a query you have to do the following things:

• Create a query
• Pass the query toFind,FindOne,MustFind orMustFindOne of the store
• Gather the results from the result set, if the used method wasFind orMustFind

// Create the queryq := NewUserQuery().        Where(kallax.Like(Schema.User.Username, "joe%")).        Order(kallax.Asc(Schema.User.Username)).        Limit(20).        Offset(2)rs, err := store.Find(q)if err != nil {        // handle error}for rs.Next() {        user, err := rs.Get()        if err != nil {                // handle error        }}

Next will automatically close the result set when it hits the end. If you have to prematurely exit the iteration you can close it manually withrs.Close().

You can query just a single row withFindOne.

q := NewUserQuery().        Where(kallax.Eq(Schema.User.Username, "Joe"))user, err := store.FindOne(q)

You can also get all of the rows in a result without having to manually iterate the result set withFindAll.

q := NewUserQuery().        Where(kallax.Like(Schema.User.Username, "joe%")).        Order(kallax.Asc(Schema.User.Username)).        Limit(20).        Offset(2)users, err := store.FindAll(q)if err != nil {        // handle error}

By default, all columns in a row are retrieved. To not retrieve all of them, you can specify the columns to include/exclude. Take into account that partial records retrieved from the database will not be writable. To make them writable you will need toReload the object.

// Select only Username and passwordNewUserQuery().Select(Schema.User.Username, Schema.User.Password)// Select all but passwordNewUserQuery().SelectNot(Schema.User.Password)

Generated findbys

Kallax generates aFindBy for every field of your model for which it makes sense to do so. What is aFindBy? It is a shorthand to add a condition to the query for a specific field.

Consider the following model:

type Person struct {        kallax.Model        ID        int64     `pk:"autoincr"`        Name      string        BirthDate time.Time        Age       int}

FourFindBys will be generated for this model:

func (*PersonQuery) FindByID(...int64) *PersonQueryfunc (*PersonQuery) FindByName(string) *PersonQueryfunc (*PersonQuery) FindByBirthDate(kallax.ScalarCond, time.Time) *PersonQueryfunc (*PersonQuery) FindByAge(kallax.ScalarCond, int) *PersonQuery

That way, you can just do the following:

NewPersonQuery().        FindByAge(kallax.GtOrEq, 18).        FindByName("Bobby")

instead of:

NewPersonQuery().        Where(kallax.GtOrEq(Schema.Person.Age, 18)).        Where(kallax.Eq(Schema.Person.Name, "Bobby"))

Why are there three different types of methods generated?

• The primary key field is treated in a special way and allows multiple IDs to be passed, since searching by multiple IDs is a common operation.
• Types that are not often searched by equality (integers, floats, times, ...) allow an operator to be passed to them to determine the operator to use.
• Types that can only be searched by value (strings, bools, ...) only allow a value to be passed.

Count results

Instead of passing the query toFind orFindOne, you can pass it toCount to get the number of rows in the resultset.

n, err := store.Count(q)

Query with relationships

By default, no relationships are retrieved unless the query specifies so.

For each of your relationships, a method in your query is created to be able to include these relationships in your query.

One to one relationships:

// Select all posts including the user that posted themq := NewPostQuery().WithPoster()rs, err := store.Find(q)

One to one relationships are always included in the same query. So, if you have 4 one to one relationships and you want them all, only 1 query will be done, but everything will be retrieved.

One to many relationships:

// Select all users including their posts// NOTE: this is a really bad idea, because all posts will be loaded// if the N side of your 1:N relationship is big, consider querying the N store// instead of doing this// A condition can be passed to the `With{Name}` method to filter the results.q := NewUserQuery().WithPosts(nil)rs, err := store.Find(q)

To avoid the N+1 problem with 1:N relationships, kallax performs batching in this case.So, a batch of users are retrieved from the database in a single query, then all the posts for those users and finally, they are merged.This process is repeated until there are no more rows in the result.Because of this, retrieving 1:N relationships is really fast.

The default batch size is 50, you can change this using theBatchSize method all queries have.

NOTE: if a filter is passed to aWith{Name} method we can no longer guarantee that all related objects are there and, therefore, the retrieved records willnot be writable.

Reloading a model

If, for example, you have a model that is not writable because you only selected one field you can always reload it and have the full object. When the object is reloaded, all the changes made to the object that have not been saved will be discarded and overwritten with the values in the database.

err := store.Reload(user)

Reload will not reload any relationships, just the model itself. After aReload the model willalways be writable.

Querying JSON

You can query arbitrary JSON using the JSON operators defined in thekallax package. The schema of the JSON (if it's a struct, obviously for maps it is not) is also generated.

q := NewPostQuery().Where(kallax.JSONContainsAnyKey(        Schema.Post.Metadata,        "foo", "bar",))

Transactions

To execute things in a transaction theTransaction method of the model store can be used. All the operations done using the store provided to the callback will be run in a transaction.If the callback returns an error, the transaction will be rolled back.

store.Transaction(func(s *UserStore) error {        if err := s.Insert(user1); err != nil {                return err        }        return s.Insert(user2)})

The fact that a transaction receives a store with the type of the model can be a problem if you want to store several models of different types. Kallax has a method namedStoreFrom that initializes a store of the type you want to have the same underlying store as some other.

store.Transaction(func(s *UserStore) error {        var postStore PostStore        kallax.StoreFrom(&postStore, s)        for _, p := range posts {                if err := postStore.Insert(p); err != nil {                        return err                }        }        return s.Insert(user)})

Transaction can be used inside a transaction, but it does not open a new one, reuses the existing one.

Caveats

• It is not possible to use slices or arrays of types that are not one of these types:
  • Basic types (e.g.[]string,[]int64) (except forrune,complex64 andcomplex128)
  • Types that implementsql.Scanner anddriver.ValuerThe reason why this is not possible is because kallax implements support for arrays of all basic Go types by hand and also for types implementingsql.Scanner anddriver.Valuer (using reflection in this case), but without having a common interface to operate on them, arbitrary types can not be supported.For example, consider the following typetype Foo string, using[]Foo would not be supported. Know that this will fail during the scanning of rows and not in code-generation time for now. In the future, might be moved to a warning or an error during code generation.Aliases of slice types are supported, though. If we havetype Strings []string, usingStrings would be supported, as a cast like this([]string)(&slice) it's supported and[]string is supported.
• time.Time andurl.URL need to be used as is. That is, you can not use a typeFoo beingtype Foo time.Time.time.Time andurl.URL are types that are treated in a special way, if you do that, it would be the same as sayingtype Foo struct { ... } and kallax would no longer be able to identify the correct type.
• time.Time fields will be truncated to remove its nanoseconds onSave,Insert orUpdate, since PostgreSQL will not be able to store them. PostgreSQL stores times with timezones as UTC internally. So, times will come back as UTC (you can useLocal method to convert them back to the local timezone). You can change the timezone that will be used to bring times back from the database inthe PostgreSQL configuration.
• Multidimensional arrays or slices arenot supported except inside a JSON field.

Migrations

Kallax can generate migrations for your schema automatically, if you want to. It is a process completely separated from the model generation, so it does not force you to generate your migrations using kallax.

Sometimes, kallax won't be able to infer a type or you will want a specific column type for a field. You can specify so with thesqltype struct tag on a field.

type Model struct {        kallax.Model `table:"foo"`        Stuff SuperCustomType `sqltype:"bytea"`}

You can see thefull list of default type mappings between Go and SQL.

Generate migrations

To generate a migration, you have to run the commandkallax migrate.

kallax migrate --input ./users/ --input ./posts/ --out ./migrations --name initial_schema

Themigrate command accepts the following flags:

Every single migration consists of 2 files:

• TIMESTAMP_NAME.up.sql: script that will upgrade your database to this version.
• TIMESTAMP_NAME.down.sql: script that will downgrade your database to this version.

Additionally, there is alock.json file where schema of the last migration is store to diff against the current models.

Run migrations

To run a migration you can either usekallax migrate up orkallax migrate down.up will upgrade your database anddown will downgrade it.

These are the flags available forup anddown:

• If no--steps or--version are provided todown, they will do nothing. If--all is provided toup, it will upgrade the database all the way up.
• If--steps and--version are provided to eitherup ordown it will use only--version, as it is more specific.

Example:

kallax migrate up --dir ./my-migrations --dsn 'user:pass@localhost:5432/dbname?sslmode=disable' --version 1493991142

Type mappings

Any other type must be explicitly specified.

All types that are not pointers will beNOT NULL.

Custom operators

You can create custom operators with kallax using theNewOperator andNewMultiOperator functions.

NewOperator creates an operator with the specified format. It returns a function that given a schema field and a value returns a condition.

The format is a string in which:col: will get replaced with the schema field and:arg: will be replaced with the value.

var Gt = kallax.NewOperator(":col: > :arg:")// can be used like this:query.Where(Gt(SomeSchemaField, 9000))

NewMultiOperator does exactly the same as the previous one, but it accepts a variable number of values.

var In = kallax.NewMultiOperator(":col: IN :arg:")// can be used like this:query.Where(In(SomeSchemaField, 4, 5, 6))

This function already takes care of wrapping:arg: with parenthesis.

Further customization

If you need further customization, you can create your own custom operator.

You need these things:

• A condition constructor (the operator itself) that takes the field and the values to create the proper SQL expression.
• AToSqler that yields your SQL expression.

Imagine we want a greater than operator that only works with integers.

func GtInt(col kallax.SchemaField, n int) kallax.Condition {        return func(schema kallax.Schema) kallax.ToSqler {                // it is VERY important that all SchemaFields                // are qualified using the schema                return &gtInt{col.QualifiedName(schema), n}        }}type gtInt struct {        col string        val int}func (g *gtInt) ToSql() (sql string, params []interface{}, err error) {        return fmt.Sprintf("%s > ?", g.col), []interface{}{g.val}, nil}// can be used like this:query.Where(GtInt(SomeSchemaField, 9000))

For most of the operators,NewOperator andNewMultiOperator are enough, so the usage of these functions is preferred over the completely custom approach. Use it only if there is no other way to build your custom operator.

Debug SQL queries

It is possible to debug the SQL queries being executed with kallax. To do that, you just need to call theDebug method of a store. This returns a new store with debugging enabled.

store.Debug().Find(myQuery)

This will log to stdout usinglog.Printfkallax: Query: THE QUERY SQL STATEMENT, args: [arg1 arg2].

You can use a custom logger (any function with a typefunc(string, ...interface{}) using theDebugWith method instead.

func myLogger(message string, args ...interface{}) {        myloglib.Debugf("%s, args: %v", message, args)}store.DebugWith(myLogger).Find(myQuery)

Benchmarks

Here are some benchmarks againstGORM,SQLBoiler anddatabase/sql. In the future we might add benchmarks for some more complex cases and other available ORMs.

BenchmarkKallaxUpdate-4                            300   4179176 ns/op     656 B/op      25 allocs/opBenchmarkKallaxUpdateWithRelationships-4           200   5662703 ns/op    6642 B/op     175 allocs/opBenchmarkKallaxInsertWithRelationships-4           200   5648433 ns/op   10221 B/op     218 allocs/opBenchmarkSQLBoilerInsertWithRelationships-4        XXX   XXXXXXX ns/op    XXXX B/op     XXX allocs/opBenchmarkRawSQLInsertWithRelationships-4           200   5427503 ns/op    4516 B/op     127 allocs/opBenchmarkGORMInsertWithRelationships-4             200   6196277 ns/op   35080 B/op     610 allocs/opBenchmarkKallaxInsert-4                            300   3916239 ns/op    1218 B/op      29 allocs/opBenchmarkSQLBoilerInsert-4                         300   4356432 ns/op    1151 B/op      35 allocs/opBenchmarkRawSQLInsert-4                            300   4065924 ns/op    1052 B/op      27 allocs/opBenchmarkGORMInsert-4                              300   4398799 ns/op    4678 B/op     107 allocs/opBenchmarkKallaxQueryRelationships/query-4          500   2900095 ns/op  269157 B/op    6200 allocs/opBenchmarkSQLBoilerQueryRelationships/query-4      1000   2082963 ns/op  125587 B/op    5098 allocs/opBenchmarkRawSQLQueryRelationships/query-4           20  59400759 ns/op  294176 B/op   11424 allocs/opBenchmarkGORMQueryRelationships/query-4            300   4758555 ns/op 1069118 B/op   20833 allocs/opBenchmarkKallaxQuery/query-4                      3000    546742 ns/op   50673 B/op    1590 allocs/opBenchmarkSQLBoilerQuery/query-4                   2000    677839 ns/op   54082 B/op    2436 allocs/opBenchmarkRawSQLQuery/query-4                      3000    464498 ns/op   37480 B/op    1525 allocs/opBenchmarkGORMQuery/query-4                        1000   1388406 ns/op  427401 B/op    7068 allocs/opPASSok  gopkg.in/src-d/go-kallax.v1/benchmarks44.899s

As we can see on the benchmark, the performance loss is not very much compared to rawdatabase/sql, while GORMs performance loss is very big and the memory consumption is way higher. SQLBoiler, on the other hand, has a lower memory footprint than kallax (in some cases), but a bigger performance loss (though not very significant), except for queries with relationships (that is a regression, though, and should be improved in the future).

Source code of the benchmarks can be found on thebenchmarks folder.

Notes:

• Benchmark runs are out of date as of 2018-05-28 (result of PR #269), some results are pending a re-run and will be updated soon.
• Benchmarks were run on a 2015 MacBook Pro with i5 and 8GB of RAM and 128GB SSD hard drive running fedora 25.
• Benchmark ofdatabase/sql for querying with relationships is implemented with a very naive 1+n solution. That's why the result is that bad.

Acknowledgements

• Big thank you to theMasterminds/squirrel library, which is an awesome query builder used internally in this ORM.
• lib/pq, the Golang PostgreSQL driver that ships with a ton of support for builtin Go types.
• mattes/migrate, a Golang library to manage database migrations.

Contributing

Reporting bugs

Kallax is a code generation tool, so it obviously has not been tested with all possible types and cases. If you find a case where the code generation is broken, please report an issue providing a minimal snippet for us to be able to reproduce the issue and fix it.

Suggesting features

Kallax is a very opinionated ORM that works for us, so changes that make things not work for us or add complexity via configuration will not be considered for adding.If we decide not to implement the feature you're suggesting, just keep in mind that it might not be because it is not a good idea, but because it does not work for us or is not aligned with the direction we want kallax to be moving forward.

Running tests

For obvious reasons, an instance of PostgreSQL is required to run the tests of this package.

By default, it assumes that an instance exists at0.0.0.0:5432 with an user, password and database name all equal totesting.

If that is not the case you can set the following environment variables:

• DBNAME: name of the database
• DBUSER: database user
• DBPASS: database user password

License

MIT, seeLICENSE

Constants¶

Variables¶

var (// ErrNonNewDocument non-new documents cannot be insertedErrNonNewDocument =errors.New("kallax: cannot insert a non new document")// ErrNewDocument a new documents cannot be updatedErrNewDocument =errors.New("kallax: cannot updated a new document")// ErrEmptyID a document without ID cannot be used with Save methodErrEmptyID =errors.New("kallax: a record without id is not allowed")// ErrNoRowUpdate is returned when an update operation does not affect any// rows, meaning the model being updated does not exist.ErrNoRowUpdate =errors.New("kallax: update affected no rows")// ErrNotWritable is returned when a record is not writable.ErrNotWritable =errors.New("kallax: record is not writable")// ErrStop can be returned inside a ForEach callback to stop iteration.ErrStop =errors.New("kallax: stopped ForEach execution")// ErrInvalidTxCallback is returned when a nil callback is passed.ErrInvalidTxCallback =errors.New("kallax: invalid transaction callback given")// ErrNotFound is returned when a certain entity is not found.ErrNotFound =errors.New("kallax: entity not found")// ErrCantSetID is returned when a model is inserted and it does not have// neither an autoincrement primary key nor implements the IDSetter// interface.ErrCantSetID =errors.New("kallax: model does not have an auto incrementable primary key, it needs to implement IDSetter interface")// ErrNoColumns is an error returned when the user tries to insert a model// with no other columns than the autoincrementable primary key.ErrNoColumns =errors.New("kallax: your model does not have any column besides its autoincrementable primary key and cannot be inserted"))

var ErrEmptyVirtualColumn =fmt.Errorf("empty virtual column")

var (// ErrManyToManyNotSupported is returned when a many to many relationship// is added to a query.ErrManyToManyNotSupported =errors.New("kallax: many to many relationships are not supported"))

var ErrRawScan =errors.New("kallax: result set comes from raw query, use RawScan instead")

var ErrRawScanBatching =errors.New("kallax: cannot perform a raw scan on a batching result set")

Functions¶

func ApplyAfterEvents(rRecord, wasPersistedbool)error

func ApplyBeforeEvents(rRecord)error

func ColumnNames(columns []SchemaField) []string

func NewMultiOperator(formatstring) func(SchemaField, ...interface{})Condition

func NewOperator(formatstring) func(SchemaField, interface{})Condition

func RecordValues(recordValuer, columns ...string) ([]interface{}, []string,error)

func StoreFrom(to, fromGenericStorer)

func VirtualColumn(colstring, rRecord, idIdentifier)sql.Scanner

Types¶

type AfterDeleter interface {// AfterDelete will do some operations after being deleted. If an error is// returned, it will cause the delete to be rolled back.AfterDelete()error}

type AfterInserter interface {// AfterInsert will do some operations after being inserted. If an error is// returned, it will cause the insert to be rolled back.AfterInsert()error}

type AfterSaver interface {// AfterSave will do some operations after being inserted or updated. If an// error is returned, it will cause the insert or update to be rolled back.AfterSave()error}

type AfterUpdater interface {// AfterUpdate will do some operations after being updated. If an error is// returned, it will cause the update to be rolled back.AfterUpdate()error}

type ArraySchemaField interface {SchemaField// contains filtered or unexported methods}

type BaseQuery struct {// contains filtered or unexported fields}

func NewBaseQuery(schemaSchema) *BaseQuery

func (q *BaseQuery) AddRelation(schemaSchema, fieldstring, typRelationshipType, filterCondition)error

func (q *BaseQuery) BatchSize(sizeuint64)

func (q *BaseQuery) Copy() *BaseQuery

func (q *BaseQuery) GetBatchSize()uint64

func (q *BaseQuery) GetLimit()uint64

func (q *BaseQuery) GetOffset()uint64

func (q *BaseQuery) Limit(nuint64)

func (q *BaseQuery) Offset(nuint64)

func (q *BaseQuery) Order(cols ...ColumnOrder)

func (q *BaseQuery) Schema()Schema

func (q *BaseQuery) Select(columns ...SchemaField)

func (q *BaseQuery) SelectNot(columns ...SchemaField)

func (q *BaseQuery) String()string

func (q *BaseQuery) ToSql() (string, []interface{},error)

func (q *BaseQuery) Where(condCondition)

q.Where(Eq(NameColumn, "foo"))q.Where(Gt(AgeColumn, 18))// ... WHERE name = "foo" AND age > 18

type BaseResultSet struct {*sql.Rows// contains filtered or unexported fields}

func NewResultSet(rows *sql.Rows, readOnlybool, relationships []Relationship, columns ...string) *BaseResultSet

func (rs *BaseResultSet) Get(schemaSchema) (Record,error)

func (rs *BaseResultSet) RawScan(dest ...interface{})error

func (rs *BaseResultSet) Scan(recordRecord)error

type BaseSchema struct {// contains filtered or unexported fields}

func NewBaseSchema(table, aliasstring, idSchemaField, fksForeignKeys, ctorRecordConstructor, autoIncrbool, columns ...SchemaField) *BaseSchema

func (s *BaseSchema) Alias()string

func (s *BaseSchema) Columns() []SchemaField

func (s *BaseSchema) ForeignKey(fieldstring) (*ForeignKey,bool)

func (s *BaseSchema) ID()SchemaField

func (s *BaseSchema) New()Record

func (s *BaseSchema) Table()string

func (s *BaseSchema) WithAlias(fieldstring)Schema

type BaseSchemaField struct {// contains filtered or unexported fields}

func (f *BaseSchemaField) QualifiedName(schemaSchema)string

func (fBaseSchemaField) String()string

type BatchingResultSet struct {// contains filtered or unexported fields}

func NewBatchingResultSet(runner *batchQueryRunner) *BatchingResultSet

func (rs *BatchingResultSet) Close()error

func (rs *BatchingResultSet) Get(_Schema) (Record,error)

func (rs *BatchingResultSet) Next()bool

func (rs *BatchingResultSet) RawScan(_ ...interface{})error

type BeforeDeleter interface {// BeforeDelete will do some operations before being deleted. If an error is// returned, it will prevent the delete from happening.BeforeDelete()error}

type BeforeInserter interface {// BeforeInsert will do some operations before being inserted. If an error is// returned, it will prevent the insert from happening.BeforeInsert()error}

type BeforeSaver interface {// BeforeSave will do some operations before being updated or inserted. If an// error is returned, it will prevent the update or insert from happening.BeforeSave()error}

type BeforeUpdater interface {// BeforeUpdate will do some operations before being updated. If an error is// returned, it will prevent the update from happening.BeforeUpdate()error}

type ColumnAddresser interface {// ColumnAddress returns the pointer to the column value of the given// column name, or an error if it does not exist in the model.ColumnAddress(string) (interface{},error)}

type ColumnOrder interface {// ToSql returns the SQL representation of the column with its order.ToSql(Schema)string// contains filtered or unexported methods}

func Asc(colSchemaField)ColumnOrder

func Desc(colSchemaField)ColumnOrder

type Condition func(Schema)ToSqler

func And(conds ...Condition)Condition

func ArrayContainedBy(colSchemaField, values ...interface{})Condition

func ArrayContains(colSchemaField, values ...interface{})Condition

func ArrayEq(colSchemaField, values ...interface{})Condition

func ArrayGt(colSchemaField, values ...interface{})Condition

func ArrayGtOrEq(colSchemaField, values ...interface{})Condition

func ArrayLt(colSchemaField, values ...interface{})Condition

func ArrayLtOrEq(colSchemaField, values ...interface{})Condition

func ArrayNotEq(colSchemaField, values ...interface{})Condition

func ArrayOverlap(colSchemaField, values ...interface{})Condition

func Eq(colSchemaField, value interface{})Condition

func Gt(colSchemaField, value interface{})Condition

func GtOrEq(colSchemaField, value interface{})Condition

func Ilike(colSchemaField, valuestring)Condition

func In(colSchemaField, values ...interface{})Condition

func JSONContainedBy(colSchemaField, elem interface{})Condition

func JSONContains(colSchemaField, elem interface{})Condition

func JSONContainsAllKeys(colSchemaField, keys ...string)Condition

func JSONContainsAny(colSchemaField, elems ...interface{})Condition

func JSONContainsAnyKey(colSchemaField, keys ...string)Condition

func JSONIsArray(colSchemaField)Condition

func JSONIsObject(colSchemaField)Condition

func Like(colSchemaField, valuestring)Condition

func Lt(colSchemaField, value interface{})Condition

func LtOrEq(colSchemaField, value interface{})Condition

func MatchRegex(colSchemaField, patternstring)Condition

func MatchRegexCase(colSchemaField, patternstring)Condition

func Neq(colSchemaField, value interface{})Condition

func Not(condCondition)Condition

func NotIn(colSchemaField, values ...interface{})Condition

func NotMatchRegex(colSchemaField, patternstring)Condition

func NotMatchRegexCase(colSchemaField, patternstring)Condition

func NotSimilarTo(colSchemaField, valuestring)Condition

func Or(conds ...Condition)Condition

func SimilarTo(colSchemaField, valuestring)Condition

type ForeignKey struct {*BaseSchemaFieldInversebool}

func NewForeignKey(namestring, inversebool) *ForeignKey

type ForeignKeys map[string]*ForeignKey

type GenericStorer interface {// GenericStore returns the generic store in this type.GenericStore() *Store// SetGenericStore sets the generic store for this type.SetGenericStore(*Store)}

type Identifiable interface {// GetID returns the ID.GetID()Identifier}

type Identifier interface {sql.Scannerdriver.Valuer// Equals reports whether the identifier and the given one are equal.Equals(Identifier)bool// IsEmpty returns whether the ID is empty or not.IsEmpty()bool// Raw returns the internal value of the identifier.Raw() interface{}}

type JSONKeyTypestring

const (// JSONAny represents a type that can't be casted.JSONAnyJSONKeyType = ""// JSONText is a text json type.JSONTextJSONKeyType = "text"// JSONInt is a numeric json type.JSONIntJSONKeyType = "bigint"// JSONFloat is a floating point json type.JSONFloatJSONKeyType = "decimal"// JSONBool is a boolean json type.JSONBoolJSONKeyType = "bool")

type JSONSchemaArray struct {// contains filtered or unexported fields}

func NewJSONSchemaArray(fieldstring, paths ...string) *JSONSchemaArray

func (f *JSONSchemaArray) QualifiedName(schemaSchema)string

func (f *JSONSchemaArray) String()string

type JSONSchemaKey struct {// contains filtered or unexported fields}

func NewJSONSchemaKey(typJSONKeyType, fieldstring, paths ...string) *JSONSchemaKey

func (f *JSONSchemaKey) QualifiedName(schemaSchema)string

func (f *JSONSchemaKey) String()string

type LoggerFunc func(string, ...interface{})

type Model struct {// contains filtered or unexported fields}

type MyModel struct {kallax.ModelFoo string}

type MyModel struct {kallax.Model `table:"custom_name"`}

func NewModel()Model

func (m *Model) AddVirtualColumn(namestring, vIdentifier)

func (m *Model) ClearVirtualColumns()

func (m *Model) IsPersisted()bool

func (m *Model) IsSaving()bool

func (m *Model) IsWritable()bool

func (m *Model) SetSaving(savingbool)

func (m *Model) VirtualColumn(namestring)Identifier

type NumericIDint64

func (idNumericID) Equals(otherIdentifier)bool

func (idNumericID) IsEmpty()bool

func (idNumericID) Raw() interface{}

func (id *NumericID) Scan(src interface{})error

func (idNumericID) String()string

func (idNumericID) Value() (driver.Value,error)

type Persistable interface {// IsPersisted returns whether this Model is new in the store or not.IsPersisted()bool// contains filtered or unexported methods}

type Query interface {// Schema returns the schema of the query model.Schema()Schema// GetOffset returns the number of skipped rows in the query.GetOffset()uint64// GetLimit returns the max number of rows retrieved by the query.GetLimit()uint64// GetBatchSize returns the number of rows retrieved by the store per// batch. This is only used and has effect on queries with 1:N// relationships.GetBatchSize()uint64// contains filtered or unexported methods}

type Record interface {IdentifiablePersistableWritableRelationableColumnAddresserValuerVirtualColumnContainerSaveable}

type RecordConstructor func()Record

type RecordWithSchema struct {SchemaSchemaRecordRecord}

type Relationable interface {// NewRelationshipRecord returns a new Record for the relationship at the// given field.NewRelationshipRecord(string) (Record,error)// SetRelationship sets the relationship value at the given field.SetRelationship(string, interface{})error}

type Relationship struct {// Type is the kind of relationship this is.TypeRelationshipType// Field is the field in the record where the relationship is.Fieldstring// Schema is the schema of the relationship.SchemaSchema// Filter establishes the filter to be applied when retrieving rows of the// relationships.FilterCondition}

type RelationshipTypebyte

const (// OneToOne is a relationship between one record in a table and another in// another table.OneToOneRelationshipType =iota// OneToMany is a relationship between one record in a table and multiple// in another table.OneToMany// ManyToMany is a relationship between many records on both sides of the// relationship.// NOTE: It is not supported yet.ManyToMany)

type ResultSet interface {// RawScan allows for raw scanning of fields in a result set.RawScan(...interface{})error// Next moves the pointer to the next item in the result set and returns// if there was any.Next()bool// Get returns the next record of the given schema.Get(Schema) (Record,error)io.Closer}

type Saveable interface {IsSaving()boolSetSaving(bool)}

type ScalarCond func(colSchemaField, value interface{})Condition

type Schema interface {// Alias returns the name of the alias used in queries for this schema.Alias()string// Table returns the table name.Table()string// ID returns the name of the identifier of the table.ID()SchemaField// Columns returns the list of columns in the schema.Columns() []SchemaField// ForeignKey returns the name of the foreign key of the given model field.ForeignKey(string) (*ForeignKey,bool)// WithAlias returns a new schema with the given string added to the// default alias.// Calling WithAlias on a schema returned by WithAlias not return a// schema based on the child, but another based on the parent.WithAlias(string)Schema// New creates a new record with the given schema.New()Record// contains filtered or unexported methods}

type SchemaField interface {// String returns the string representation of the field. That is, its name.String()string// QualifiedString returns the name of the field qualified by the alias of// the given schema.QualifiedName(Schema)string// contains filtered or unexported methods}

func AtJSONPath(fieldSchemaField, typJSONKeyType, path ...string)SchemaField

func NewSchemaField(namestring)SchemaField

type Store struct {// contains filtered or unexported fields}

func NewStore(db *sql.DB) *Store

func (s *Store) Count(qQuery) (countint64, errerror)

func (s *Store) Debug() *Store

func (s *Store) DebugWith(loggerLoggerFunc) *Store

func (s *Store) Delete(schemaSchema, recordRecord)error

func (s *Store) DisableCacher() *Store

func (s *Store) Find(qQuery) (ResultSet,error)

func (s *Store) Insert(schemaSchema, recordRecord)error

func (s *Store) MustCount(qQuery)int64

func (s *Store) MustFind(qQuery)ResultSet

func (s *Store) RawExec(sqlstring, params ...interface{}) (int64,error)

func (s *Store) RawQuery(sqlstring, params ...interface{}) (ResultSet,error)

func (s *Store) Reload(schemaSchema, recordRecord)error

func (s *Store) Save(schemaSchema, recordRecord) (updatedbool, errerror)

func (s *Store) Transaction(callback func(*Store)error)error

func (s *Store) Update(schemaSchema, recordRecord, cols ...SchemaField) (int64,error)

type Timestamps struct {// CreatedAt is the time where the object was created.CreatedAttime.Time// UpdatedAt is the time where the object was updated.UpdatedAttime.Time}

type MyModel struct {kallax.Modelkallax.TimestampsFoo string}

func (t *Timestamps) BeforeSave()error

type ToSqler interface {squirrel.Sqlizer}

type ULIDuuid.UUID

func NewULID()ULID

func NewULIDFromText(textstring) (ULID,error)

func (idULID) Equals(otherIdentifier)bool

func (idULID) IsEmpty()bool

func (idULID) MarshalText() ([]byte,error)

func (idULID) Raw() interface{}

func (id *ULID) Scan(src interface{})error

func (idULID) String()string

func (u *ULID) UnmarshalText(text []byte) (errerror)

func (idULID) Value() (driver.Value,error)

type UUIDuuid.UUID

func (idUUID) Equals(otherIdentifier)bool

func (idUUID) IsEmpty()bool

func (idUUID) Raw() interface{}

func (id *UUID) Scan(src interface{})error

func (idUUID) String()string

func (idUUID) Value() (driver.Value,error)

type Valuer interface {// Value returns the value of the given column, or an error if it does not// exist in the model.Value(string) (interface{},error)}

type VirtualColumnContainer interface {// ClearVirtualColumns removes all virtual columns.ClearVirtualColumns()// AddVirtualColumn adds a new virtual column with the given name and valueAddVirtualColumn(string,Identifier)// VirtualColumn returns the virtual column with the given column name.VirtualColumn(string)Identifier// contains filtered or unexported methods}

type Writable interface {// IsWritable returns whether this Model can be saved into the database.IsWritable()bool// contains filtered or unexported methods}