go-firestorm
Go ORM (Object-relational mapping) for Google Cloud Firestore.
Goals
- Easy to use
- Non-intrusive
- Non-exclusive
- Fast
Features
- Basic CRUD operations
- Search
- Concurrent requests support (except when run in transactions)
- Transactions
- Nested transactions will reuse the first transaction (reads before writes as required by firestore)
- Configurable auto load of references
- Handles cyclic references
- Sub collections
- Supports embedded/anonymous structs
- Supports unexported fields
- Custom mappers between fields and types
- Caching (session + second level)
- Supports Google App Engine - 2. Gen (go version >= 1.11)
Getting Started
- Prerequisites
- Basic CRUD example
- Search
- Concurrent requests
- Transactions
- Cache
- Configurable auto load of references
- Customize data mapping
- Help
Prerequisites
This library only supports Firestore Native mode and not the old Datastore mode.
go get -u github.com/jschoedt/go-firestorm
Setup
- Setup a Firestore client
- Create a firestorm client and supply the names of the id and parent fields of your model structs. Parent is optional. The id field must be a string but can be called anything.
...
client, _ := app.Firestore(ctx)
fsc := firestorm.New(client, "ID", "")- Optional. For optimal caching to work consider adding the CacheHandler.
Basic CRUD example
Note: Recursive Create/Delete is not supported and must be called on every entity. So to create an A->B relation. Create B first so the B.ID has been created and then create A.
type Car struct {
ID string
Make string
Year time.Time
}car := &Car{}
car.Make = "Toyota"
car.Year, _ = time.Parse(time.RFC3339, "2001-01-01T00:00:00.000Z")
// Create the entity
fsc.NewRequest().CreateEntities(ctx, car)()
if car.ID == "" {
t.Errorf("car should have an auto generated ID")
}
// Read the entity by ID
otherCar := &Car{ID:car.ID}
fsc.NewRequest().GetEntities(ctx, otherCar)()
if otherCar.Make != "Toyota" {
t.Errorf("car should have name: Toyota but was: %s", otherCar.Make)
}
if otherCar.Year != car.Year {
t.Errorf("car should have same year: %s", otherCar.Year)
}
// Update the entity
car.Make = "Jeep"
fsc.NewRequest().UpdateEntities(ctx, car)()
otherCar := &Car{ID:car.ID}
fsc.NewRequest().GetEntities(ctx, otherCar)()
if otherCar.Make != "Jeep" {
t.Errorf("car should have name: Jeep but was: %s", otherCar.Make)
}
// Delete the entity
fsc.NewRequest().DeleteEntities(ctx, car)()
otherCar = &Car{ID:car.ID}
if err := fsc.NewRequest().GetEntities(ctx, otherCar)(); err == nil {
t.Errorf("We expect a NotFoundError")
}Search
Create a query using the firebase client
car := &Car{}
car.ID = "testID"
car.Make = "Toyota"
fsc.NewRequest().CreateEntities(ctx, car)()
query := fsc.Client.Collection("Car").Where("make", "==", "Toyota")
result := make([]Car, 0)
if err := fsc.NewRequest().QueryEntities(ctx, query, &result)(); err != nil {
t.Errorf("car was not found by search: %v", car)
}
if result[0].ID != car.ID || result[0].Make != car.Make {
t.Errorf("entity did not match original entity : %v", result)
}Concurrent requests
All CRUD operations are asynchronous and return a future func that when called will block until the operation is done.
NOTE: the state of the entities is undefined until the future func returns.
car := &Car{Make:"Toyota"}
// Create the entity which returns a future func
future := fsc.NewRequest().CreateEntities(ctx, car)
// ID is not set
if car.ID != "" {
t.Errorf("car ID should not have been set yet")
}
// do some more work
// blocks and waits for the database to finish
future()
// now the car has been saved and the ID has been set
if car.ID == "" {
t.Errorf("car should have an auto generated ID now")
}Transactions
Transactions are simply done in a function using the transaction context
car := &Car{Make: "Toyota"}
fsc.DoInTransaction(ctx, func(transCtx context.Context) error {
// Create the entity in the transaction using the transCtx
fsc.NewRequest().CreateEntities(transCtx, car)()
// Using the transCtx we can load the entity as it is saved in the session context
otherCar := &Car{ID:car.ID}
fsc.NewRequest().GetEntities(transCtx, otherCar)()
if otherCar.Make != car.Make {
t.Errorf("The car should have been saved in the transaction context")
}
// Loading using an other context (request) will fail as the car is not created until the func returns successfully
if err := fsc.NewRequest().GetEntities(ctx, &Car{ID:car.ID})(); err == nil {
t.Errorf("We expect a NotFoundError")
}
})
// Now we can load the car as the transaction has been committed
otherCar := &Car{ID:car.ID}
fsc.NewRequest().GetEntities(ctx, otherCar)()
if otherCar.Make != "Toyota" {
t.Errorf("car should have name: Toyota but was: %s", otherCar.Make)
}Cache
Firestorm supports adding a session cache to the context. The session cache only caches entities that are loaded within the same request.
# add it to a single handler:
http.HandleFunc("/", firestorm.CacheHandler(otherHandler))
# or add it to the routing chain (for gorilla/mux, go-chi etc.):
r.Use(firestorm.CacheMiddleware)To add a second level cache (such as Redis or memcache) the Cache interface needs to be implemented and added to the client:
fsc.SetCache(c)Firestore will first try to fetch an entity from the session cache. If it is not found it will try the second level cache.
Configurable auto load of references
Use the req.SetLoadPaths("fieldName") to auto load a particular field or req.SetLoadPaths(firestorm.AllEntities) to load all fields.
Load an entity path by adding multiple paths eg.: path->to->field
fsc.NewRequest().SetLoadPaths("path", "path.to", "path.to.field").GetEntities(ctx, car)()Customize data mapping
This library uses go-structmapper for mapping values between Firestore and structs. The mapping can be customized by setting the mappers:
fsc.MapToDB = mapper.New()
fsc.MapFromDB = mapper.New()Help
Help is provided in the go-firestorm User Group