pq

Neuron Postgres

neuron-pq is the github.com/neuronlabs/neuron-core postgres repository driver.

• What is Neuron-PQ
• Installation
• QuickStart
• Docs
• Examples
• Options
• Neuron-Core

What is Neuron-PQ

Neuron-PQ is the PostgreSQL ORM Repository driver for the github.com/neuronlabs/neuron-core.

Installation

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

Neuron-pq is the extension for the Neuron-Core requires github.com/neuronlabs/neuron-core root package.

QuickStart

1. Prepare or read the Config Repository - github.com/neuronlabs/neuron-core/config by creating structure or by using viper github.com/spf13/viper and create the neuron controller The DriverName variable (driver_name in config) should be set to pq in order to match the neuron-pq Repository and Factory

 var controllerConfig *config.Controller

 cfg := &config.Repository{
    DriverName: "pq",
    Host: "localhost",
    Port: 5432,
    DBName:"dbname",
    ...
 }

 controllerConfig.Repositories = map[string]*config.Repository{
    "mypostgres": cfg,    
    // Add more custom repository configurations for different models if you 
    // need different connection or credentials
}


... 

c, err = controller.New(cfg)
...

1. Register the neuron-pq repository for you application by initializing the repository package

import (
    _ "github.com/neuronlabs/neuron-pq"
)

1. Define the models

// User
type User struct {
    ID      int     `neuron:"type=primary"`
    Name    string  `neuron:"type=attr"`
    Surname string  `neuron:"type=attr"`
    Cars    []*Car  `neuron:"type=relation"`
}
// define the repository if any other would be used

// RepositoryName returns the name of the repository used by the User model
func (u *User) RepositoryName() string {
    return "mypostgres"
}

// Car
type Car struct {
    ID              int     `neuron:"type=primary"`
    RegisterNumber  string  `neuron:"type=attr" db="unique"`
    Owner           *User   `neuron:"type=relation;foreign=OwnerID"`
    OwnerID         string  `neuron:"type=foreign" db="notnull"`
}

// RepositoryName returns the name of the repository used by the Car model
func (c *Car) RepositoryName() string {
    return "mypostgres"
}

1. Register the models

if err = c.RegisterModels(&User{}, &Car{}); err != nil {
    // handle the error for invalid model definitions
}

1. Use the models within the Gateway API or just as an ORM models.

user := &User{
    Name: "Mathew",
    Surname: "Smith",
}
s, err := query.NewC(c, user)
if err != nil {
    // handle the error
}

if err = s.Create(); err != nil {
    // handle the error
}

Examples

config.yml

{
    "repositories": {
        "postgres": {
            "driver_name": "pq",
            "host": "localhost",
            "port": "5432",
            "dbname": "testing",
            "username": "testing",
            "password": "testing"
        }
    },
    "default_repository_name": "postgres",
    "models": {
            "car": {
                "repository_name" : "postgres",
                "automigrate": true
            }
        }
    }
}

package main

import (
    "github.com/neuronlabs/neuron-core/config"
    "github.com/neuronlabs/neuron-core/controller"
    "github.com/neuronlabs/neuron-core/query/scope"
    _ "github.com/neuronlabs/neuron-pq"
)

// Car is the model used in our example application
type Car struct {
    ID      int             `neuron:"type=primary"`
    Brand   *Manufacturer   `neuron:"type=relation;foreign=BrandID"`
    BrandID int             `neuron:"type=foreign"`
    VIN     string          `neuron:"type=attr" db:"unique"`
}

// Manufacturer is the model used in our example application defined as a car 
// manufacturer
type Manufacturer struct {
    ID      int     `neuron:"type=primary"`
    Name    string  `neuron:"type=attr"`
    Cars    []*Car  `neuron:"type=relation;foreign=BrandID"`
}


func main() {
    // read the config from file named 'config' in the path './'
    cfg, err := config.ReadControllerConfig("config", "./")
    if err != nil {
        panic(err)
    }

    // create the controller with the config
    c, err := controller.New(cfg)
    if err != nil {
        panic(err)
    }

    // even thought only the car is defined in the model
    // the manufacturer would have the defined repository - taken from the 
    // default
    if err := c.RegisterModels(&Car{}, &Manufacturer{}); err != nil {
        panic(err)
    }


    manufacturer := &Manufacturer{
        Name: "Best Manufacturer",
    }

    s, err := query.NewC(c, manufacturer)
    if err != nil {
        panic(err)
    }

    if err = s.Create(); err != nil {
        panic(err)
    }

    car := &Car{
        VIN: "1HGBH41JXMN109186"
        BrandID: 1,
    }

    s, err = query.NewC(c, car)
    if err != nil {
        panic(err)
    }

    if err = s.Create(); err != nil {
        panic(err)
    }


    // your database should contain now one entry of the manufacturer with 
    // name "Best Manufacturer" and one car with VIN number: 
    // '1HGBH41JXMN109186' and foreign key to brand - brand_id = 1
    ... 
}

Docs

• Neuron-Core: https://docs.neuronlabs.io/neuron-core
• Neuron-PQ: https://docs.neuronlabs.io/neuron-pq
• GoDoc: https://godoc.org/github.com/neuronlabs/neuron-pq
• Project Neuron: https://docs.neuronlabs.io

Options

The neuron-pq have an option to AutoMigrate the models. AutoMigration checks the model's table definition on the current database connection. If there is no such table it creates new one. If any column is missing it creates it with all the constraint defined.

In order to set the AutoMigrate for all models within a provided Repository Set it's config.Options with the key AutoMigrateKey to true in:

 var cfg *config.Repository 
 cfg = &config.Repository{Options: map[string]interface{}{AutoMigrateKey: true}

If AutoMigrate should migrate all the models within any neuron-pq.Repositoryinstance the package variable AutoMigrateAll should be set to true

The third option to set the AutoMigrate just for single model is to set it's Config (*config.Model) AutoMigrate variable to true.