octopus

README

Octopus

Octopus is an ORM/ODM written in Golang. It supports SQL and NoSQL databases and is easy to use.

Get Started

Run the following command to get octopus package

go get -u -t github.com/Kamva/octopus

Usage

For using octopus you need a scheme and a model. Scheme represent the field in your desired table (or collection), and Model is the struct that interact with the database.

Note that the scheme must implement octopus/base.Scheme interface. The model struct must embed the octopus.Model and run Initiate method on its constructor.

package models

import (
    "github.com/Kamva/octopus"
    "github.com/Kamva/octopus/base"
)


type User struct {
    // This is optional. This only adds `GetKeyName` method implementation that
    // returns `id` by default. for MongoDB you should use `octopus.MongoScheme`
    // or implemet `GetKeyName` method yourself, as default primary key in Mongo
    // is `_id`.
    octopus.Scheme
    ID          int     `sql:"pk"`
    Name        string  `sql:"column:full_name"`
    Email       string  `sql:"unique"`
    Password    string
    RawData     map[string]string `sql:"ignore"` // Add ignore tag if the field does not exists on table
}

func (u User) GetID() interface{} {
	return u.ID
}

type UserModel struct {
    octopus.Model
}

func NewUserModel() *UserModel {
    model :=  &UserModel{}
    config := base.DBConfig{Driver:base.PG, Host:"localhost", Port: "5432", Database: "MyDatabase"}
    model.Initiate(&User{}, config)
    
    return model
}

Then you can use model like this:

package main

import (
    "github.com/Kamva/octopus/term"
	"models"
)


func main() {
	model := models.NewUserModel()
	
	// Find a user by ID
	user, err := model.Find(1)
	if err != nil {
		panic(err)
	}
	
	// Create a new record
	newUser := User{Name: "John Doe", Email: "john.doe@email.com", Password: "HashedPassword"}
	model.Create(&newUser)
	
	// Update a record
	user.Name = "New Name"
	model.Update(user)
	
	// Delete a record
	model.Delete(user)
	
	// Query the table
	model.Where(term.Equal{Field: "name", Value: "John Doe"}).First()
}

Supported Databases

• MongoDB
  • Data Modelling
  • Raw Query
  • Aggregations
  • Relation Support [via lookup aggregation]
• PostgreSQL
  • Data Modelling
  • Arrays and Json type support
  • Grouping
  • Raw Query
  • Relation Support
• MSSQL
  • Data Modelling
  • Grouping
  • Raw Query
  • Relation Support
  • Stored Procedures
• MySQL
• SQLite3

Documentation

Index

• type Builder
  • func NewBuilder(builder base.QueryBuilder, model *Model) *Builder
  • func (b *Builder) All() ([]base.Scheme, error)
  • func (b *Builder) Count() (int, error)
  • func (b *Builder) Delete() (int, error)
  • func (b *Builder) First() (base.Scheme, error)
  • func (b *Builder) Limit(n int) base.Builder
  • func (b *Builder) OrderBy(sorts ...base.Sort) base.Builder
  • func (b *Builder) Skip(n int) base.Builder
  • func (b *Builder) Update(data base.Scheme) (int, error)
• type Configurator
• type Model
  • func (m *Model) CloseClient()
  • func (m *Model) Create(data base.Scheme) error
  • func (m *Model) Delete(data base.Scheme) error
  • func (m *Model) EnsureIndex(indices ...base.Index)
  • func (m *Model) Find(id interface{}) (base.Scheme, error)
  • func (m *Model) GetClient() base.Client
  • func (m *Model) GetCollection() (base.MongoCollection, error)
  • func (m *Model) Initiate(scheme base.Scheme, config base.DBConfig, configurators ...Configurator)
  • func (m *Model) PrepareClient()
  • func (m *Model) Update(data base.Scheme) error
  • func (m *Model) Where(query ...base.Condition) base.Builder
• type MongoScheme
  • func (s MongoScheme) GetKeyName() string
• type Scheme
  • func (s Scheme) GetKeyName() string

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder is a wrapper around QueryBuilder that convert RecordData object to model's related scheme.

func NewBuilder

func NewBuilder(builder base.QueryBuilder, model *Model) *Builder

NewBuilder instantiate Builder with given QueryBuilder

func (*Builder) All

func (b *Builder) All() ([]base.Scheme, error)

All returns results that match with query conditions in RecordDataSet format. If the query conditions was empty it will return all records in specified destination table or error if anything went wrong.

func (*Builder) Count

func (b *Builder) Count() (int, error)

Count execute a count command that will return the number records in specified destination table. If the query conditions was empty, it returns number of all records un destination table.

func (*Builder) Delete

func (b *Builder) Delete() (int, error)

Delete removes every records in destination table that match with condition query and returns number of affected rows and error if anything went wrong. It will removes all records inside destination table if no condition query was set.

func (*Builder) First

func (b *Builder) First() (base.Scheme, error)

First fetch data of the first record that match with query conditions.

func (*Builder) Limit

func (b *Builder) Limit(n int) base.Builder

Limit set the limit that determines how many results should be returned in the following fetch command.

func (*Builder) OrderBy

func (b *Builder) OrderBy(sorts ...base.Sort) base.Builder

OrderBy set the order of returning result in following command

func (*Builder) Skip

func (b *Builder) Skip(n int) base.Builder

Skip set the starting offset of the following fetch command

func (*Builder) Update

func (b *Builder) Update(data base.Scheme) (int, error)

Update updates records that math with query conditions with `data` and returns number of affected rows and error if anything went wring. If the query condition was empty it'll update all records in destination table.

type Configurator

type Configurator func(*Model)

Configurator is a function for configuring Model attributes. Usually it is used for adding indices or configure table name, or even configuring drivers with custom drivers

type Model

type Model struct {
	// contains filtered or unexported fields
}

Model is an object that responsible for interacting

func (*Model) CloseClient

func (m *Model) CloseClient()

CloseClient close and destroy client connection

func (*Model) Create

func (m *Model) Create(data base.Scheme) error

Create inserts the given filled scheme into model table/collection and return inserted record/document or error if there was any fault in data insertion.

func (*Model) Delete

func (m *Model) Delete(data base.Scheme) error

Delete find a record/document that match with data ID and remove it from related table/collection. It will return error if anything went wrong

func (*Model) EnsureIndex

func (m *Model) EnsureIndex(indices ...base.Index)

EnsureIndex checks for table/collection existence in database, if not found tries to create it. Then it ensures that given indices are exists on table/collection.

func (*Model) Find

func (m *Model) Find(id interface{}) (base.Scheme, error)

Find search for a record/document in model table/collection match with given ID

func (*Model) GetClient

func (m *Model) GetClient() base.Client

GetClient returns database client. Note that client should be closed after use.

func (*Model) GetCollection

func (m *Model) GetCollection() (base.MongoCollection, error)

GetCollection returns collection object for mongo db.

func (*Model) Initiate

func (m *Model) Initiate(scheme base.Scheme, config base.DBConfig, configurators ...Configurator)

Initiate initialize the model and prepare it for interacting with database

func (*Model) PrepareClient

func (m *Model) PrepareClient()

PrepareClient Prepare client for further actions

func (*Model) Update

func (m *Model) Update(data base.Scheme) error

Update find a record/document that match with data ID and updates its field with data values. It'll return error if anything went wrong during update

func (*Model) Where

func (m *Model) Where(query ...base.Condition) base.Builder

Where returns a Query Builder based on given conditions on model table/collection that you can fetch, update or delete records/document match the query.

type MongoScheme

type MongoScheme struct{}

MongoScheme is the base scheme, same as Scheme, for mongo db schemes

func (MongoScheme) GetKeyName

func (s MongoScheme) GetKeyName() string

GetKeyName return the name of primary key field name

type Scheme

type Scheme struct{}

Scheme is the base scheme that other schemes can embed to have default methods

func (Scheme) GetKeyName

func (s Scheme) GetKeyName() string

GetKeyName return the name of primary key field name