neuron

Neuron Core

neuron is the golang cloud-native, distributed ORM implementation.

• What is Neuron?
• Install
• Docs
• Quick Start
• Packages
• Design

What is neuron?

neuron is a cloud-ready Golang ORM. It's design allows querying multiple related models located on different data stores or repositories using a single API.

Design

Package neuron provides golang ORM implementation designed to process microservice repositories. This concept enhanced the requirements for the models mapping and query processor.

The mapped models must have all the field's with defined type. The initial model mapping was based on the JSONAPI v1.0 model definition. The distributed environment required each relationship to be specified of it's kind and type, just as their foreign keys.

The query processor works as the orchestrator and choreographer. It allows to join the queries where each model's use a different database. It also allows distributed transactions transactions.

Install

go get github.com/neuronlabs/neuron

Docs

• neuron: https://docs.neuronlabs.io/neuron
• GoDoc: https://godoc.org/github.com/neuronlabs/neuron
• Project Neuron: https://docs.neuronlabs.io

Quick Start

• Define the models

package models

// User is the model that is stored on the 'main' repository.
// It is related to multiple 'Pet' models.
type User struct {
    ID      int
    Name    string
    Surname string
    Pets    []*Pet `neuron:"foreign=OwnerID"`
}

// Pet is the model related with the User.
// It is stored in the 'secondary' repository.
type Pet struct {
    ID          int
    Name        string
    OwnerID     int     `neuron:"type=foreign"`
}

// RepositoryName implements RepositoryNamer interface.
func (p *Pet) RepositoryName() string {
    return "secondary"
}

• Import repositories and Create, Read or get Default *config.Controller

package main

import (
    "context"
    // blank imported repository registers it's factory
    // and the driver.
    _ "github.com/neuronlabs/neuron-postgres"

    "github.com/neuronlabs/neuron"
    "github.com/neuronlabs/neuron/config"
    "github.com/neuronlabs/neuron/log"

)

func main() {
    cfg := config.Default()
    // Provided create config 'cfg' to the Controller method.
    n, err := neuron.New(cfg)
    if err != nil {
        log.Fatal(err)
    } 

    // As the 'neuron' allows to use multiple repository for the models
    // we can declare the DefaultRepository within the config. The first 
    // registered repository would be set as the default as well. 
    mainDB := &config.Repository{
        // Currently registered repository 'neuron-pq' has it's driver name: 'pq'.
        DriverName: "postgres",        
        Host: "localhost",   
        Port: 5432,
        Username: "main_db_user",
        Password: "main_db_password",
        DBName: "main",
    }
    if err = n.RegisterRepository("main", mainDB); err != nil {
        log.Fatal(err)
    }

    // We can register and use different repository for other models.
    secondaryDB := &config.Repository{        
        DriverName: "postgres",        
        Host: "172.16.1.10",
        Port: 5432,
        Username: "secondary_user",
        Password: "secondary_password",
        DBName: "secondary",
    }

    // Register secondary repository.
    if err = n.RegisterRepository("secondary", secondaryDB); err != nil {
        log.Fatal(err)
    }

    if err = n.DialAll(context.TODO()); err != nil {
        log.Fatal(err)    
    }
    
    // Register models 
    if err = n.RegisterModels(models.User{}, models.Pet{}); err != nil {
        log.Fatal(err)
    }

    // If necessary migrate the models
    if err = n.MigrateModels(models.User{}, models.Pet{}); err != nil {
        log.Fatal(err)
    }

    // Start application and query models
    users := []*models.User{}
    err = n.Query(&users).        
        .Filter("Name IN","John", "Sam"). // Filter the results by the 'Name' which might be 'John' or 'Sam'.        
        .Sort("-ID"). // Sort the results by user's ids.
        .Include("Pets"). // Include the 'Pets' field for each user in the 'users'.
        .List() // List all the users with the name 'John' or 'Sam' with 'id' ordered in decrease manner.
    if  err != nil {
        log.Fatal(err)
    }
    log.Infof("Queried users: %v", users)
}

Packages

The neuron is composed of the following packages:

• query - used to query the model's repositories.
• controller - is the neuron's core, that registers and stores the models and contains configurations required by other packages.
• mapping - contains the information about the mapped models their fields and settings
• config - contains the configurations structures.
• class - contains github.com/neuronlabs/errors class instances used by the neuron package.
• repository - is a package used to store, get and register the repositories nad their factories.
• log - is the logging interface for the neuron based applications.