gorm

package
v0.24.4 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2021 License: Apache-2.0 Imports: 26 Imported by: 3

README

GORM

This package contains a set of utilities for famous GORM library. If used together they can significantly help you to enable persistency in your application.

Collection Operators

The package provides some helpers which are able to apply collection operators defined in query package to a GORM query.

Applying query.Filtering
...
// given that Person is a protobuf message and PersonORM is a corresponding GORM model
db, assoc, err = gorm.ApplyFiltering(ctx, db, filtering, &PersonORM{}, &Person{})
if err != nil {
    ...
}
// Join required associations(for nested field support)
db, err = gorm.JoinAssociations(ctx, db, assoc, &PersonORM{})
if err != nil {
    ...
}
var people []Person
db.Find(&people)
...
Applying query.Sorting
...
db, assoc, err = gorm.ApplySorting(ctx, db, sorting, &PersonORM{}, &Person{})
if err != nil {
    ...
}
// Join required associations(for nested field support)
db, err = gorm.JoinAssociations(ctx, db, assoc, &PersonORM{})
if err != nil {
    ...
}
var people []Person
db.Find(&people)
...
Applying query.Pagination
...
db = gorm.ApplyPagination(ctx, db, pagination, &PersonORM{}, &Person{})
if err != nil {
    ...
}
var people []Person
db.Find(&people)
...
Applying query.FieldSelection
...
db, err = gorm.ApplyFieldSelection(ctx, db, fields, &PersonORM{}, &Person{})
if err != nil {
    ...
}
var people []Person
db.Find(&people)
...
Applying everything
...
db, err = gorm.ApplyCollectionOperators(ctx, db, &PersonORM{}, &Person{}, filtering, sorting, pagination, fields)
if err != nil {
    ...
}
var people []Person
db.Find(&people)
...

Transaction Management

We provide transaction management by offering gorm.Transaction wrapper and gorm.UnaryServerInterceptor. The gorm.Transaction works as a singleton to prevent an application of creating more than one transaction instance per incoming request. The gorm.UnaryServerInterceptor performs management on transactions. Interceptor creates new transaction on each incoming request and commits it if request finishes without error, otherwise transaction is aborted. The created transaction is stored in context.Context and passed to the request handler as usual.

NOTE Client is responsible to call txn.Begin() to open transaction.

// add gorm interceptor to the chain
  server := grpc.NewServer(
    grpc.UnaryInterceptor(
      grpc_middleware.ChainUnaryServer( // middleware chain
        ...
        gorm.UnaryServerInterceptor(), // transaction management
        ...
      ),
    ),
  )

import (
	"github.com/kirinse/atlas-app-toolkit/gorm"
)

func (s *MyService) MyMethod(ctx context.Context, req *MyMethodRequest) (*MyMethodResponse, error) {
	// extract gorm transaction from context
	txn, ok := gorm.FromContext(ctx)
	if !ok {
		return panic("transaction is not opened") // don't panic in production!
	}
	// start transaction
	gormDB := txn.Begin()
	if err := gormDB.Error; err != nil {
		return nil, err
	}
	// do stuff with *gorm.DB
	return &MyMethodResponse{...}, nil
}

Migration version validation

The toolkit does not require any specific method for database provisioning and setup. However, if golang-migrate or the infobloxopen fork of it is used, a couple helper functions are provided here for verifying that the database version matches a required version without having to import the entire migration package.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrCtxTxnMissing = errors.New("Database transaction for request missing in context")
	ErrCtxTxnNoDB    = errors.New("Transaction in context, but DB is nil")
)
View Source 
var (
	DefaultSchemaNamer schema.Namer = schema.NamingStrategy{}
)

Functions

func ApplyCollectionOperators deprecated 

func ApplyCollectionOperators(ctx context.Context, db *gorm.DB, obj interface{}, pb proto.Message, f *query.Filtering, s *query.Sorting, p *query.Pagination, fs *query.FieldSelection) (*gorm.DB, error)

Deprecated: use ApplyCollectionOperatorsEx instead ApplyCollectionOperators applies collection operators to gorm instance db.

func ApplyCollectionOperatorsEx added in v0.18.0 

func ApplyCollectionOperatorsEx(ctx context.Context, db *gorm.DB, obj interface{}, c CollectionOperatorsConverter, f *query.Filtering, s *query.Sorting, p *query.Pagination, fs *query.FieldSelection) (*gorm.DB, error)

func ApplyFieldSelection deprecated 

func ApplyFieldSelection(ctx context.Context, db *gorm.DB, fs *query.FieldSelection, obj interface{}) (*gorm.DB, error)

Deprecated: use ApplyFieldSelectionEx instead ApplyFieldSelection applies field selection operator fs to gorm instance db.

func ApplyFieldSelectionEx added in v0.18.0 

func ApplyFieldSelectionEx(ctx context.Context, db *gorm.DB, fs *query.FieldSelection, obj interface{}, c FieldSelectionConverter) (*gorm.DB, error)

ApplyFieldSelectionEx applies field selection operator fs to gorm instance db.

func ApplyFiltering deprecated 

func ApplyFiltering(ctx context.Context, db *gorm.DB, f *query.Filtering, obj interface{}, pb proto.Message) (*gorm.DB, map[string]struct{}, error)

Deprecated: use ApplyFilteringEx instead ApplyFiltering applies filtering operator f to gorm instance db.

func ApplyFilteringEx added in v0.18.0 

func ApplyFilteringEx(ctx context.Context, db *gorm.DB, f *query.Filtering, obj interface{}, c FilteringConditionConverter) (*gorm.DB, map[string]struct{}, error)

ApplyFiltering applies filtering operator f to gorm instance db.

func ApplyPagination 

func ApplyPagination(ctx context.Context, db *gorm.DB, p *query.Pagination) *gorm.DB

ApplyPagination applies pagination operator p to gorm instance db.

func ApplyPaginationEx added in v0.18.0 

func ApplyPaginationEx(ctx context.Context, db *gorm.DB, p *query.Pagination, c PaginationConverter) *gorm.DB

ApplyPaginationEx applies pagination operator p to gorm instance db.

func ApplySorting deprecated 

func ApplySorting(ctx context.Context, db *gorm.DB, s *query.Sorting, obj interface{}) (*gorm.DB, map[string]struct{}, error)

Deprecated: use ApplySortingEx instead ApplySorting applies sorting operator s to gorm instance db.

func ApplySortingEx added in v0.18.0 

func ApplySortingEx(ctx context.Context, db *gorm.DB, s *query.Sorting, obj interface{}, c SortingCriteriaConverter) (*gorm.DB, map[string]struct{}, error)

ApplySorting applies sorting operator s to gorm instance db.

func BeginFromContext added in v0.6.0 

func BeginFromContext(ctx context.Context) (*gorm.DB, error)

BeginFromContext will extract transaction wrapper from context and start new transaction. As result new instance of `*gorm.DB` will be returned. Error will be returned in case either transaction or db connection info is missing in context. Gorm specific error can be checked by `*gorm.DB.Error`.

func BeginWithOptionsFromContext added in v0.21.0 

func BeginWithOptionsFromContext(ctx context.Context, opts *sql.TxOptions) (*gorm.DB, error)

BeginWithOptionsFromContext will extract transaction wrapper from context and start new transaction, options can be specified to control isolation level for transaction. As result new instance of `*gorm.DB` will be returned. Error will be returned in case either transaction or db connection info is missing in context. Gorm specific error can be checked by `*gorm.DB.Error`.

func FieldSelectionStringToGorm added in v0.7.0 

func FieldSelectionStringToGorm(ctx context.Context, fs string, obj interface{}) ([]string, error)

FieldSelectionStringToGorm is a shortcut to parse a string into FieldSelection struct and receive a list of associations to preload.

func FilterStringToGorm 

func FilterStringToGorm(ctx context.Context, filter string, obj interface{}, pb proto.Message) (string, []interface{}, map[string]struct{}, error)

FilterStringToGorm is a shortcut to parse a filter string using default FilteringParser implementation and call FilteringToGorm on the returned filtering expression.

func FilteringToGorm deprecated 

func FilteringToGorm(ctx context.Context, m *query.Filtering, obj interface{}, pb proto.Message) (string, []interface{}, map[string]struct{}, error)

Deprecated: Use FilteringToGormEx instead FilteringToGorm returns GORM Plain SQL representation of the filtering expression.

func FilteringToGormEx added in v0.18.0 

func FilteringToGormEx(ctx context.Context, m *query.Filtering, obj interface{}, c FilteringConditionConverter) (string, []interface{}, map[string]struct{}, error)

FilteringToGorm returns GORM Plain SQL representation of the filtering expression.

func HandleFieldPath added in v0.7.0 

func HandleFieldPath(ctx context.Context, fieldPath []string, obj interface{}) (string, string, error)

HandleFieldPath converts fieldPath to appropriate db string for use in where/order by clauses according to obj GORM model. If fieldPath cannot be found in obj then original fieldPath is returned to allow tables joined by a third party. If association join is required to resolve the field path then it's name is returned as a second return value.

func HandleJSONFieldPath added in v0.17.0 

func HandleJSONFieldPath(ctx context.Context, fieldPath []string, obj interface{}, values ...string) (string, string, error)

HandleJSONFiledPath translate field path to JSONB path for postgres jsonb

func IsJSONCondition added in v0.17.0 

func IsJSONCondition(ctx context.Context, fieldPath []string, obj interface{}) bool

TODO: add supprt for embeded objects

func JoinAssociations added in v0.7.0 

func JoinAssociations(ctx context.Context, db *gorm.DB, assoc map[string]struct{}, obj interface{}) (*gorm.DB, error)

JoinAssociations joins obj's associations from assoc to the current gorm query.

func JoinInfo added in v0.7.0 

func JoinInfo(ctx context.Context, obj interface{}, assoc string) (string, []string, []string, error)

JoinInfo extracts the following information for assoc association of obj: - association table name - source join keys - target join keys

func MergeWithMask added in v0.8.0 

func MergeWithMask(source, dest interface{}, mask *fieldmask.FieldMask) error

MergeWithMask will take the fields of `source` that are included as paths in `mask` and write them to the corresponding fields of `dest`

func NewContext added in v0.5.0 

func NewContext(parent context.Context, txn *Transaction) context.Context

NewContext returns a new Context that carries value txn.

func UnaryServerInterceptor added in v0.5.0 

func UnaryServerInterceptor(db *gorm.DB) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns grpc.UnaryServerInterceptor that manages a `*Transaction` instance. New *Transaction instance is created before grpc.UnaryHandler call. Client is responsible to call `txn.Begin()` to open transaction. If call of grpc.UnaryHandler returns with an error the transaction is aborted, otherwise committed.

func UnaryServerInterceptorTxn added in v0.24.2 

func UnaryServerInterceptorTxn(txn *Transaction) grpc.UnaryServerInterceptor

func VerifyMigrationVersion added in v0.14.1 

func VerifyMigrationVersion(db *jgorm.DB, v MigrationVersionValidator) error

VerifyMigrationVersion checks the schema_migrations table of the db passed against the ValidVersion function of the given validator, returning an error for an invalid version or a dirty database

Types

type CollectionOperatorsConverter added in v0.18.0 

type CollectionOperatorsConverter interface {
	FilteringConditionConverter
	SortingCriteriaConverter
	FieldSelectionConverter
	PaginationConverter
}

func NewDefaultPbToOrmConverter added in v0.18.0 

func NewDefaultPbToOrmConverter(pb proto.Message) CollectionOperatorsConverter

NewDefaultPbToOrmConverter creates default converter for all collection operators

type DefaultFieldSelectionConverter added in v0.18.0 

type DefaultFieldSelectionConverter struct{}

DefaultFieldSelectionConverter performs default convertion for FieldSelection collection operator

func (*DefaultFieldSelectionConverter) FieldSelectionToGorm added in v0.18.0 

func (converter *DefaultFieldSelectionConverter) FieldSelectionToGorm(ctx context.Context, fs *query.FieldSelection, obj interface{}) ([]string, error)

FieldSelectionToGorm receives FieldSelection struct and returns a list of associations to preload.

type DefaultFilteringConditionConverter added in v0.18.0 

type DefaultFilteringConditionConverter struct {
	Processor FilteringConditionProcessor
}

DefaultFilteringConditionConverter performs default convertion for Filter collection operator

func (*DefaultFilteringConditionConverter) LogicalOperatorToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) LogicalOperatorToGorm(ctx context.Context, lop *query.LogicalOperator, obj interface{}) (string, []interface{}, map[string]struct{}, error)

LogicalOperatorToGorm returns GORM Plain SQL representation of the logical operator.

func (*DefaultFilteringConditionConverter) NullConditionToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) NullConditionToGorm(ctx context.Context, c *query.NullCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)

NullConditionToGorm returns GORM Plain SQL representation of the null condition.

func (*DefaultFilteringConditionConverter) NumberArrayConditionToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) NumberArrayConditionToGorm(ctx context.Context, c *query.NumberArrayCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)

func (*DefaultFilteringConditionConverter) NumberConditionToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) NumberConditionToGorm(ctx context.Context, c *query.NumberCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)

NumberConditionToGorm returns GORM Plain SQL representation of the number condition.

func (*DefaultFilteringConditionConverter) StringArrayConditionToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) StringArrayConditionToGorm(ctx context.Context, c *query.StringArrayCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)

func (*DefaultFilteringConditionConverter) StringConditionToGorm added in v0.18.0 

func (converter *DefaultFilteringConditionConverter) StringConditionToGorm(ctx context.Context, c *query.StringCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)

StringConditionToGorm returns GORM Plain SQL representation of the string condition.

type DefaultFilteringConditionProcessor added in v0.18.0 

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

DefaultFilteringConditionProcessor processes filter operator conversion

func (*DefaultFilteringConditionProcessor) ProcessStringCondition added in v0.18.0 

func (p *DefaultFilteringConditionProcessor) ProcessStringCondition(ctx context.Context, fieldPath []string, value string) (interface{}, error)

ProcessStringCondition processes a string condition to GORM Plain SQL representation

type DefaultPaginationConverter added in v0.18.0 

type DefaultPaginationConverter struct{}

DefaultPaginationConverter performs default convertion for Paging collection operator

func (*DefaultPaginationConverter) PaginationToGorm added in v0.18.0 

func (converter *DefaultPaginationConverter) PaginationToGorm(ctx context.Context, p *query.Pagination) (offset, limit int32)

type DefaultPbToOrmConverter added in v0.18.0 

type DefaultPbToOrmConverter struct {
	DefaultFilteringConditionConverter
	DefaultSortingCriteriaConverter
	DefaultFieldSelectionConverter
	DefaultPaginationConverter
}

DefaultPbToOrmConverter performs default convertion for all collection operators

type DefaultSortingCriteriaConverter added in v0.18.0 

type DefaultSortingCriteriaConverter struct{}

DefaultSortingCriteriaConverter performs default convertion for Sorting collection operator

func (*DefaultSortingCriteriaConverter) SortingCriteriaToGorm added in v0.18.0 

func (converter *DefaultSortingCriteriaConverter) SortingCriteriaToGorm(ctx context.Context, cr *query.SortCriteria, obj interface{}) (string, string, error)

type EmptyFieldPathError added in v0.7.0 

type EmptyFieldPathError struct {
}

func (*EmptyFieldPathError) Error added in v0.7.0 

func (e *EmptyFieldPathError) Error() string

type FieldSelectionConverter added in v0.18.0 

type FieldSelectionConverter interface {
	FieldSelectionToGorm(ctx context.Context, fs *query.FieldSelection, obj interface{}) ([]string, error)
}

type FilteringConditionConverter added in v0.18.0 

type FilteringConditionConverter interface {
	LogicalOperatorConverter
	NullConditionConverter
	StringConditionConverter
	StringArrayConditionConverter
	NumberConditionConverter
	NumberArrayConditionConverter
}

type FilteringConditionProcessor added in v0.18.0 

type FilteringConditionProcessor interface {
	ProcessStringCondition(ctx context.Context, fieldPath []string, value string) (interface{}, error)
}

type LogicalOperatorConverter added in v0.18.0 

type LogicalOperatorConverter interface {
	LogicalOperatorToGorm(ctx context.Context, lop *query.LogicalOperator, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type MigrationVersionValidator added in v0.14.1 

type MigrationVersionValidator interface {
	ValidVersion(int64) error
}

MigrationVersionValidator has a function for checking the database version

func MaxVersionFrom added in v0.14.1 

func MaxVersionFrom(path string) (MigrationVersionValidator, error)

MaxVersionFrom returns a MigrationVersionValidator with a target based on the highest numbered migration file detected in the given directory

func VersionExactly added in v0.14.1 

func VersionExactly(version int64) MigrationVersionValidator

VersionExactly returns a MigrationVersionValidator with a specific target version

func VersionRange added in v0.14.1 

func VersionRange(lower, upper int64) MigrationVersionValidator

VersionRange returns a MigrationVersionValidator with a given lower and upper bound

type NullConditionConverter added in v0.18.0 

type NullConditionConverter interface {
	NullConditionToGorm(ctx context.Context, c *query.NullCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type NumberArrayConditionConverter added in v0.18.0 

type NumberArrayConditionConverter interface {
	NumberArrayConditionToGorm(ctx context.Context, c *query.NumberArrayCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type NumberConditionConverter added in v0.18.0 

type NumberConditionConverter interface {
	NumberConditionToGorm(ctx context.Context, c *query.NumberCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type PaginationConverter added in v0.18.0 

type PaginationConverter interface {
	PaginationToGorm(ctx context.Context, p *query.Pagination) (offset, limit int32)
}

type SortingCriteriaConverter added in v0.18.0 

type SortingCriteriaConverter interface {
	SortingCriteriaToGorm(ctx context.Context, cr *query.SortCriteria, obj interface{}) (string, string, error)
}

type StringArrayConditionConverter added in v0.18.0 

type StringArrayConditionConverter interface {
	StringArrayConditionToGorm(ctx context.Context, c *query.StringArrayCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type StringConditionConverter added in v0.18.0 

type StringConditionConverter interface {
	StringConditionToGorm(ctx context.Context, c *query.StringCondition, obj interface{}) (string, []interface{}, map[string]struct{}, error)
}

type Transaction added in v0.5.0 

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

Transaction serves as a wrapper around `*gorm.DB` instance. It works as a singleton to prevent an application of creating more than one transaction instance per incoming request.

func FromContext added in v0.5.0 

func FromContext(ctx context.Context) (txn *Transaction, ok bool)

FromContext returns the *Transaction value stored in ctx, if any.

func NewTransaction added in v0.9.0 

func NewTransaction(db *gorm.DB) Transaction

func (*Transaction) AddAfterCommitHook added in v0.7.0 

func (t *Transaction) AddAfterCommitHook(hooks ...func(context.Context))

func (*Transaction) Begin added in v0.5.0 

func (t *Transaction) Begin() *gorm.DB

Begin starts new transaction by calling `*gorm.DB.Begin()` Returns new instance of `*gorm.DB` (error can be checked by `*gorm.DB.Error`)

func (*Transaction) BeginWithOptions added in v0.21.0 

func (t *Transaction) BeginWithOptions(opts *sql.TxOptions) *gorm.DB

BeginWithOptions starts new transaction by calling `*gorm.DB.BeginTx()` Returns new instance of `*gorm.DB` (error can be checked by `*gorm.DB.Error`)

func (*Transaction) Commit added in v0.5.0 

func (t *Transaction) Commit(ctx context.Context) error

Commit finishes transaction by calling `*gorm.DB.Commit()` Reset current transaction and returns an error if any.

func (*Transaction) Rollback added in v0.5.0 

func (t *Transaction) Rollback() error

Rollback terminates transaction by calling `*gorm.DB.Rollback()` Reset current transaction and returns an error if any.

Source Files

View all Source files

Directories

Path Synopsis

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.