schemaver

Documentation

Overview

Package schemaver provides a way to manage your data schema version.

Index

• Constants
• func Initialize() error
• func RegisterProtocol(proto string, backend Backend)
• type Backend
• type Manage
• type SchemaVer
  • func New() (*SchemaVer, error)
  • func NewAt(location string) (*SchemaVer, error)
  • func (v *SchemaVer) AddCallback(callback func(string))
  • func (v *SchemaVer) Close() error
  • func (v *SchemaVer) ExclusiveLock() string
  • func (v *SchemaVer) Get() string
  • func (v *SchemaVer) HoldSharedLock(ctx context.Context, relockEvery time.Duration)
  • func (v *SchemaVer) Set(ver string)
  • func (v *SchemaVer) SharedLock() string
  • func (v *SchemaVer) Unlock()

Constants

const (
	// NoVersion will be set as version value while initialization.
	NoVersion = "none"
	// BadVersion must be set as version value in case data schema may
	// be incorrect (as result of interrupted migration or restoring
	// backup).
	BadVersion = "dirty"
	// EnvLocation must contain url pointing to location of data
	// schema version. For example: file:///some/path/.
	EnvLocation = "NARADA4D"
	// EnvSkipLock must be set to non-empty value in case
	// ExclusiveLock was already acquired (by parent process).
	EnvSkipLock = "NARADA4D_SKIP_LOCK"
)

Functions

func Initialize

func Initialize() error

Initialize initialize version at location provided in $NARADA4D.

Version must not be already initialized.

func RegisterProtocol

func RegisterProtocol(proto string, backend Backend)

RegisterProtocol must be called by packages which implement some protocol before first call to Initialize or New.

Types

type Backend

type Backend struct {
	// New returns implementation of SchemaVerBackend working with
	// version at given location or error if location is incorrect.
	New func(*url.URL) (Manage, error)
	// Initialize version at given location or return error if
	// location is incorrect or already initialized.
	Initialize func(*url.URL) error
}

Backend used for registering backend implementing concrete protocol.

type Manage

type Manage interface {
	// SharedLock must acquire shared lock on version value.
	//
	// If called with already acquired lock previous lock may be
	// released before acquiring new one.
	SharedLock()
	// ExclusiveLock must acquire exclusive lock on version value.
	//
	// If called with already acquired lock previous lock may be
	// released before acquiring new one.
	ExclusiveLock()
	// Unlock will be called after SharedLock or ExclusiveLock and
	// must release lock on version value.
	Unlock()
	// Get will be called after SharedLock or ExclusiveLock and must
	// return current version.
	Get() string
	// Set will be called after ExclusiveLock and must change current
	// version.
	Set(string)
	// Close will release any resources used to manage schema version.
	Close() error
}

Manage interface must be implemented by concrete data schema version managing protocols.

type SchemaVer

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

SchemaVer manage data schema versions.

func New

func New() (*SchemaVer, error)

New creates object for managing data schema version at location provided in $NARADA4D.

Will initialize version if it's not initialized yet.

func NewAt

func NewAt(location string) (*SchemaVer, error)

NewAt creates object for managing data schema version at location.

Will initialize version if it's not initialized yet.

func (*SchemaVer) AddCallback

func (v *SchemaVer) AddCallback(callback func(string))

AddCallback registers user-provided function which will be called with current version in parameter by each SharedLock or ExclusiveLock before they returns.

Usually this function should check is current version is supported by this application and call log.Fatal if not.

func (*SchemaVer) Close

func (v *SchemaVer) Close() error

Close release any resources used to manage schema version.

No other methods should be called after Close.

func (*SchemaVer) ExclusiveLock

func (v *SchemaVer) ExclusiveLock() string

ExclusiveLock acquire exclusive lock and return current version.

It may be called recursively, under already acquired ExclusiveLock (in this case it'll do nothing).

func (*SchemaVer) Get

func (v *SchemaVer) Get() string

Get returns current version.

It must be called under SharedLock or ExclusiveLock.

func (*SchemaVer) HoldSharedLock

func (v *SchemaVer) HoldSharedLock(ctx context.Context, relockEvery time.Duration)

HoldSharedLock will start goroutine which will acquire SharedLock and keep it until Close or ctx.Done. It'll release and immediately re-acquire SharedLock every relockEvery to give someone else a chance to get ExclusiveLock.

This is recommended optimization in case you've to do a lot of short-living SharedLock every second.

func (*SchemaVer) Set

func (v *SchemaVer) Set(ver string)

Set change current version.

It must be called under ExclusiveLock.

func (*SchemaVer) SharedLock

func (v *SchemaVer) SharedLock() string

SharedLock acquire shared lock and return current version.

It may be called recursively, under already acquired SharedLock or ExclusiveLock (in this case it'll do nothing).

func (*SchemaVer) Unlock

func (v *SchemaVer) Unlock()

Unlock release lock acquired using SharedLock or ExclusiveLock.

When called to unlock previous SharedLock or ExclusiveLock which did nothing (because lock was already acquired) then it will do nothing too.