getting-started.md

description
ObjectBox Go database is designed for high performance on restricted devices and will give you instant speed on all CRUD operations. It is easy to use; just follow this tutorial to get started.

Get started on-the-go

Creating an Entity

Using ObjectBox in your project is fairly straight-forward.

First of all, let's define an Entity which is just a struct. It could be located basically anywhere but to keep our project structure clean, let's have it in a internal/model/task.go i. e. model package.

{% code title="internal/model/task.go" %}

package model

//go:generate go run github.com/objectbox/objectbox-go/cmd/objectbox-gogen

// Put this on a new line to enable sync: // `objectbox:"sync"`
type Task struct {
	Id           uint64
	Text         string
	DateCreated  int64
	DateFinished int64
}

{% endcode %}

{% hint style="info" %} Note that Id uint64 is recognized by ObjectBox to contain an ID field which gives us a direct access to the stored Tasks objects by their ID.

Alternatively if your ID field is named differently, you can annotate it with `objectbox:"id"`.
For more information see Entity Annotations. {% endhint %}

Having the entity file, we can run bindings generator to get the necessary task.obx.go

cd my-project-dir
go generate ./...

The generated bindings code has two main competencies:

• provide Entity model (schema) to the ObjectBox
• convert between internal object representation (FlatBuffers) and our struct Task

{% hint style="warning" %} Additionally to the task.obx.go there's an objectbox-model.json which holds information about the model and objectbox-model.go which defines a model initialization function. All these files should be committed in source control along with the rest of your code. {% endhint %}

Initializing ObjectBox

To use ObjectBox in our main application code, we use Builder and give it model information and optionally some other settings. The code with the model information is generated by the ObjectBox and you just need to use in your code:

import (
	"github.com/objectbox/objectbox-go/objectbox"
	"github.com/objectbox/objectbox-go/examples/tasks/internal/model"
)

func initObjectBox() *objectbox.ObjectBox {
	objectBox, err := objectbox.NewBuilder().Model(model.ObjectBoxModel()).Build()
	return objectBox
}

Working with Object Boxes

Bet you wondered where our name comes from :)

From ObjectBox you vend Box instances to manage your entities. While you can have multiple Box instances of the same type (for the same Entity) "open" at once, it's usually preferable to just use one instance and pass it around your code.

{% code title="main.go" %}

func main() {
   // load objectbox
   ob := initObjectBox()
   defer ob.Close() // In a server app, you would just keep ob and close on shutdown
   
   box := model.BoxForTask(ob)
   
   // Create
   id, _ := box.Put(&model.Task{
      Text: "Buy milk",
   })
   
   task, _ := box.Get(id) // Read
   task.Text += " & some bread"
   box.Put(task)         // Update
   box.Remove(task)      // Delete
}

{% endcode %}

Wherever you have access to a Box, you can use it to persist objects and fetch objects from disk. Boxes are thread safe. Here are some of the basic operations:

• Put: Persist an object, which may overwrite an existing object with the same ID. In other words, use Putto insert or update objects. When put succeeds, an ID will be assigned to the entity.
• Get: When you have an object's ID, you can get to the object very efficiently using Get. It will return nil & error in case an error occurred and nil without any error if the object doesn't exist.
  To get all objects of a type, use GetAllwhich returns a slice.
• Remove: Deletes a previously persisted object from its box. Use RemoveAll to delete all objects and empty the box.
• Count: The number of objects stored in this box.

Task-list example application

To see it all put together, have a look at the Task-List application example in our git repository:
https://github.com/objectbox/objectbox-go/tree/main/examples