corm

package module
v0.0.0-...-4138937 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 11, 2018 License: Apache-2.0 Imports: 6 Imported by: 0

README

CORM

The awesome CouchDB ORM library for Golang, aims to be developer friendly.

GoDoc Go Report Card

Overview

  • Our goal is to adapt/implement the Domain-Classes Methods from grails and some of the CouchDB specific Api for CouchDb
  • Be careful when using. The api can changed. We are in early state.
  • If you have some suggestions or concerns please contact us or make a issue ticket.

Requirements

  • CouchDB >= 2.1
  • Golang >= 1.9

Installation

go get -u github.com/SerkanSipahi/corm
ORM methods (our goal for a Nosql-Database)
db methods
ctx := context.TODO()
db, err := corm.New(ctx, corm.Config{
    DBName: "myDatabase",
})
  • Save
  • Read
  • Update
  • Delete
  • First
  • Last
  • Count
  • CountBy
  • Exists
  • BelongsTo
  • DeleteMany
  • ExecuteQuery
  • UpdateAll
  • Find
  • FindAll
  • FindAllBy
  • FindAllWhere
  • FindBy
  • FindWhere
  • Get
  • GetAll
  • HasMany
  • HasOne
  • List
  • ListOrderBy
  • Refresh
  • SaveAll
  • SaveJson
  • Sync
  • Validate
  • Where
  • WhereAny
Basic usage

type Product struct {
	Id          string `json:"_id,omitempty"`  // required in this style
	Rev         string `json:"_rev,omitempty"` // required in this style
	Type        string `json:"type"`           // required: tag this but don´t touch it
	// additionals
	Name        string `json:"name"`
}

// init DB
ctx := context.TODO()
db, err := corm.New(ctx, corm.Config{
    DBName: "myDatabase",
})

// save document with custom Id
docId, rev, err := db.Save(ctx, Product{
    Id:   "111-222-333",
    Name: "Foo",
})

// save document with auto Id
docId, rev, err = db.Save(ctx, Product{
    Name: "Bar",
})

// update document
rev, err = db.Update(ctx, Product{
    Id:   docId,
    Rev:  rev,
    Name: "Baz",
})

// read document
var product Product
_, err = db.Read(ctx, docId, &product)
fmt.Println(product) // product{ Id: "asdfj334234f34asdfq34", Rev: "1-alsj34lkjij3lksife" ...

// delete document
rev, err = db.Delete(ctx, docId, rev)

Author

SerkanSipahi

Contributors

https://github.com/SerkanSipahi/corm/graphs/contributors

License

This software is released under the terms of the Apache 2.0 license. See LICENCE.md, or read the full license.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckDocument 

func CheckDocument(doc interface{}) (structName, docId, docRev, docType string, err error)

CheckDocument checks if the required fields Id, Rev and Type are exists. When everything gone right, it return the extracted fields Id, Rev and Type. When it fails it return an error.

Types

type Client 

type Client = kivik.Client

func NewClient 

func NewClient(ctx context.Context, config ClientConfig) (*Client, error)

NewClient returns a client instance that can be used for e.g. CouchDb´ s build in authentication. Here are the full method list of the client instance: https://godoc.org/github.com/flimzy/kivik#Client

Example

Here is an example for Authentication an user 

package main

import (
	"context"
	"fmt"
	"github.com/serkansipahi/corm"
	"log"
)

func main() {

	// create client
	client, err := corm.NewClient(context.TODO(), corm.ClientConfig{
		Host:       "http://localhost:5984/",
		DriverName: "couch",
	})

	// log when it fails
	if err != nil {
		log.Fatal(err)
	}

	// define credentials
	type Credentials struct {
		Name     string `json:"name"`
		Password string `json:"password"`
	}

	// authenticate user
	err = client.Authenticate(context.TODO(), Credentials{
		Name:     "myname",
		Password: "somepassword",
	})

	fmt.Println(err)
}

Output:

nil

type ClientConfig 

type ClientConfig struct {
	Host       string // default "couch"
	DriverName string // default "http://localhost:5984/"
}

type Config 

type Config struct {
	Host       string // default "couch"
	DriverName string // default "http://localhost:5984/"
	DBName     string
}

Config can be passed in corm.New(...)

type DB 

type DB = kivik.DB

type Options 

type Options = kivik.Options

type Orm 

type Orm struct {
	Db *DB
}

Orm contains the Db instance that be used inside of corm.NewOrm(...)

func New 

func New(ctx context.Context, config Config) (*Orm, error)

New returns a db instance connection by passed DBName. When it fails it will return an error. Optionally "Host" and DriverName can be passed with Config struct. 

ctx := context.TODO()
db, err := corm.New(ctx, Config{
	DBName: "honeyglass",
})

func NewOrm 

func NewOrm(db *DB) *Orm

NewOrm creates a new Orm instance by passed db instance. Note: not relevant for you! It will be used inside of corm.New(...) but if you really want to create your own orm, please see [Example].

Example (Orm)

You dont need this step when using corm. But if want to know how to init an custom orm, please follow the example step by step. 

package main

import (
	"context"
	"fmt"
	"github.com/serkansipahi/corm"
	"log"
)

func main() {

	// type Product struct {
	// 	Id          string `json:"_id,omitempty"`  // required in this style
	// 	Rev         string `json:"_rev,omitempty"` // required in this style
	// 	Type        string `json:"type"`           // required in this style
	// 	Name        string `json:"vendorId"`
	// }

	// create client
	client, err := corm.NewClient(context.TODO(), corm.ClientConfig{
		Host:       "http://localhost:5984/",
		DriverName: "couch",
	})
	if err != nil {
		log.Fatal(err)
	}

	// create db
	db, err := client.DB(context.TODO(), "mydbname")
	// create orm
	orm := corm.NewOrm(db)
	if err != nil {
		log.Fatal(err)
	}

	// define any struct
	type Person struct {
		Name     string
		Surename string
		Age      int
	}

	// save person
	id, rev, err := orm.Save(context.TODO(), Person{
		Name:     "Serkan",
		Surename: "Sipahi",
	})

	fmt.Println(id, rev, err)
}

Output:

889c9653a6b490cc24c85d78b10076c7, 1-68a533f5dc76a65b56b7329b9d4086ab, nil

func (*Orm) Delete 

func (c *Orm) Delete(ctx context.Context, docId string, docRev ...string) (newRev string, err error)

Delete deletes the document by passed id and revision (rev). When id and revision (rev) are empty it will return an error. When everything works fine it will return the new deleted revision (newRev).

Example

Delete document 

package main

import (
	"context"
	"github.com/serkansipahi/corm"
	"log"
)

func main() {

	// create orm
	orm, err := corm.New(context.TODO(), corm.Config{
		DBName: "mydbname",
	})

	// log when it fails
	if err != nil {
		log.Fatal(err)
	}

	// delete doc
	_, err = orm.Delete(context.TODO(),
		"889c9653a6b490cc24c85d78b10076c7",
		"2-68a533f5dc76a65b56b7329b9d4086ab",
	)

	// log when it fails
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Orm) Read 

func (c *Orm) Read(ctx context.Context, docId string, doc interface{}, options ...Options) (row *Row, err error)

Read reads document from database by passed id and doc struct. When it fails it will return an empty Row and error and when everything works fine, it will unmarshal the result (row) to passed doc struct.

Example

Read document 

// type Product struct {
// 	Id          string `json:"_id,omitempty"`  // required in this style
// 	Rev         string `json:"_rev,omitempty"` // required in this style
// 	Type        string `json:"type"`           // required: tag this but don´t touch it
// 	Name        string `json:"name"`
// }

// create orm
orm, err := corm.New(context.TODO(), corm.Config{
	DBName: "mydbname",
})

// log when it fails
if err != nil {
	log.Fatal(err)
}

var product Product
_, err = orm.Read(context.TODO(), "889c9653a6b490cc24c85d78b10076c7", &product)

fmt.Println(product)

Output:

Product{Name: "Bar", Id: "889c9653a6b490cc24c85d78b10076c7", Rev: "2-68a533f5dc76a65b56b7329b9d4086ab"}

func (*Orm) Save 

func (c *Orm) Save(ctx context.Context, doc interface{}) (docId string, docRev string, err error)

Save saves new doc (struct) in the database. When it saved correctly it will return an id and revision. On fail it will return an error. When doc contain the Id property, the database will interpret it as predefined unique Id and when its omitted it will generate it automatically.

Example (Save1)

Save a document with "auto generated" id by couchDB 

// type Product struct {
// 	Id          string `json:"_id,omitempty"`  // required in this style
// 	Rev         string `json:"_rev,omitempty"` // required in this style
// 	Type        string `json:"type"`           // required: tag this but don´t touch it
// 	Name        string `json:"vendorId"`
// }

// create orm
orm, err := corm.New(context.TODO(), corm.Config{
	DBName: "mydbname",
})

if err != nil {
	log.Fatal(err)
}

// save document
docId, rev, err := orm.Save(context.TODO(), Product{
	Name: "Foo",
})

// log when it fails
if err != nil {
	log.Fatal(err)
}

fmt.Println(docId, rev, nil)

Output:

889c9653a6b490cc24c85d78b10076c7, 1-68a533f5dc76a65b56b7329b9d4086ab, nil
Example (Save2)

Save a document with "predefined" id 

// type Product struct {
// 	Id          string `json:"_id,omitempty"`  // required in this style
// 	Rev         string `json:"_rev,omitempty"` // required in this style
// 	Type        string `json:"type"`           // required: tag this but don´t touch it
// 	Name        string `json:"name"`
// }

// create orm
orm, err := corm.New(context.TODO(), corm.Config{
	DBName: "mydbname",
})

// create document with predefined id
docId, rev, err := orm.Save(context.TODO(), Product{
	Id:   "123456",
	Name: "Foo",
})

// log when it fails
if err != nil {
	log.Fatal(err)
}

fmt.Println(docId, rev, err)

Output:

123456, 1-68a533f5dc76a65b56b7329b9d4086ab, nil

func (*Orm) Update 

func (c *Orm) Update(ctx context.Context, doc interface{}) (docId, newRev string, err error)

Update updates doc (struct) as document in the database. The doc must contains the doc Id and Rev property. When its saved correctly it will return a new revision. Otherwise it will return an error.

Example

Update an document by given Id and Rev 

// type Product struct {
// 	Id          string `json:"_id,omitempty"`  // required in this style
// 	Rev         string `json:"_rev,omitempty"` // required in this style
// 	Type        string `json:"type"`           // required: tag this but don´t touch it
// 	Name        string `json:"name"`
// }

// create orm
orm, err := corm.New(context.TODO(), corm.Config{
	DBName: "mydbname",
})

// log when it fails
if err != nil {
	log.Fatal(err)
}

// update document
rev, err := orm.Update(context.TODO(), Product{
	Id:   "889c9653a6b490cc24c85d78b10076c7",
	Rev:  "1-68a533f5dc76a65b56b7329b9d4086ab",
	Name: "Bar",
})

// log when it fails
if err != nil {
	log.Fatal(err)
}

fmt.Println(rev, err)

Output:

2-68a533f5dc76a65b56b7329b9d4086ab, nil

type OrmOptions 

type OrmOptions map[string]interface{}

OrmOptions contains options as key value pair.

type Row 

type Row = kivik.Row

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.