neuron

README

Neuron Core

Neuron-core is the golang cloud-native, distributed ORM implementation.

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

What is Neuron-Core?

Neuron-core is a cloud-ready Golang ORM. It's design allows to query multiple related models located on different datastores/repositories.

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 needs to work as the orchestrator, choreographer. As each model's repository might use different database, it needs to implement distributed transactions.

Install

go get -u github.com/neuronlabs/neuron-core

Docs

• Neuron-Core: https://docs.neuronlabs.io/neuron-core
• GoDoc: https://godoc.org/github.com/neuronlabs/neuron-core
• 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:"type=relation;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

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

import (
    "github.com/neuronlabs/neuron-core"
    "github.com/neuronlabs/neuron-core/config"
)

func main() {
    cfg := config.Default()   

• Create the *controller.Controller and register repositories.

    // Provided create config 'cfg' to the Controller method.
    c := neuron.NewController(cfg)

    // As the 'neuron-core' 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: "pq",        
        Host: "localhost",   
        Port: "5432",
        Username: "main_db_user",
        Password: "main_db_password",
        DBName: "main",
    }
    if err := c.RegisterRepository("main", mainDB); err != nil {
        // handle error
    }

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

    // Register secondary repository.
    if err := c.RegisterRepository("secondary", secondaryDB); err != nil {
        // handle error
    }

    if err := c.Dial(context.TODO()); err != nil {
        // handle error    
    }

• Register models

    if err := c.RegisterModels(models.User{}, models.Pet{}); err != nil {
        // handle error
    }

• Query registered models

    users := []*User{}
    
    err := neuron.QueryC(c, &users).        
        .Filter("filter[users][name][$in]","John", "Sam"). // the query scope may be filtered        
        .Sort("-id"). // it might also be sorted
        .List() // list all the users with the name 'John' or 'Sam' with 'id' ordered in decrease manner.
    if  err != nil {
        // resolve the error
    }

Packages

The neuron-core 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-core 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.

Documentation

Overview

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

It's design allows to use the separate repository for each model, with a possibility to have different relationships types between them.

Neuron-core consists of following packages:

• neuron - (Neuron Core) the root package that gives easy access to all subpackages. .

• controller - is the neuron's core, that registers and stores the models and contains configurations required by other packages.

• config - contains the configurations for all packages.

• query - used to create queries, filters, sort, pagination on base of mapped models.

• mapping - contains the information about the mapped models their fields and settings.

• class - contains errors classification system for the neuron packages.

• log - is the logging interface for the neuron based applications.

• i18n - is the neuron based application supported internationalization.

• repository - is a package used to store and register the repositories.

  It is also used to get the repository/factory per model. A modular design allows to use and compile only required repositories.

Index

• func Begin() *query.Tx
• func BeginCtx(ctx context.Context, opts *query.TxOptions) *query.Tx
• func CloseAll(ctx context.Context) error
• func Controller() *controller.Controller
• func DialAll(ctx context.Context) error
• func HealthCheck(ctx context.Context) (*repository.HealthResponse, error)
• func InitController(cfg *config.Controller) (err error)
• func MigrateModels(ctx context.Context, models ...interface{}) error
• func NewController(cfg *config.Controller) (*controller.Controller, error)
• func Query(model interface{}) query.Builder
• func QueryC(c *controller.Controller, model interface{}) query.Builder
• func QueryCtx(ctx context.Context, model interface{}) query.Builder
• func QueryCtxC(ctx context.Context, c *controller.Controller, model interface{}) query.Builder
• func RegisterModels(models ...interface{}) error
• func RegisterRepository(name string, repo *config.Repository) error
• func RunInTransaction(ctx context.Context, txOpts *query.TxOptions, txFn TxFn) (err error)
• type TxFn

Functions

func Begin

func Begin() *query.Tx

Begin starts new transaction with the default isolation.

func BeginCtx

func BeginCtx(ctx context.Context, opts *query.TxOptions) *query.Tx

BeginCtx starts new transaction. Provided context 'ctx' is used until the transaction is committed or rolled back.

func CloseAll

func CloseAll(ctx context.Context) error

CloseAll gently closes repository connections in the default controller.

func Controller

func Controller() *controller.Controller

Controller gets default controller.

func DialAll

func DialAll(ctx context.Context) error

DialAll establish connections for all repositories in the default controller.

func HealthCheck

func HealthCheck(ctx context.Context) (*repository.HealthResponse, error)

HealthCheck checks all repositories health for the default controller.

func InitController

func InitController(cfg *config.Controller) (err error)

InitController initializes default controller for given configuration. Returns error if the default controller is already defined. In order to force initializing new controller set the controller.DefaultController to nil.

func MigrateModels

func MigrateModels(ctx context.Context, models ...interface{}) error

MigrateModels updates or creates provided models representation in their related repositories. A representation of model might be a database table, collection etc. Model's repository must implement repository.Migrator. Models are migrated for the default controller.

func NewController

func NewController(cfg *config.Controller) (*controller.Controller, error)

NewController creates and initializes controller for provided config.

func Query

func Query(model interface{}) query.Builder

Query creates new query for the provided 'model' using the default controller.

func QueryC

func QueryC(c *controller.Controller, model interface{}) query.Builder

QueryC creates new query for the provided 'model' using 'c' controller.

func QueryCtx

func QueryCtx(ctx context.Context, model interface{}) query.Builder

QueryCtx creates new query for the provided 'model' using the default controller with respect to the context 'ctx'.

func QueryCtxC

func QueryCtxC(ctx context.Context, c *controller.Controller, model interface{}) query.Builder

QueryCtxC creates new query for the provided 'model' using 'c' controller with respect to the context 'ctx'.

func RegisterModels

func RegisterModels(models ...interface{}) error

RegisterModels registers all models into default controller. This function requires repositories to be registered before. Returns error if the model was already registered.

func RegisterRepository

func RegisterRepository(name string, repo *config.Repository) error

RegisterRepository registers repository into default controller. Returns error if the repository with given name was already registered. By default the first registered repository is set to the default repository for all models that doesn't define their repositories, unless default controller's config DisallowDefaultRepository is set to false.

func RunInTransaction

func RunInTransaction(ctx context.Context, txOpts *query.TxOptions, txFn TxFn) (err error)

RunInTransaction creates a new transaction and handles rollback / commit based on the error return by the txFn.

Types

type TxFn

type TxFn func(tx *query.Tx) error

TxFn is the function used to run WithTransaction.