datamigration

Documentation

Overview

Data migration package implements a functionality to declare and execute data migrations.

Each data migration is a function registered under a unique name, that can be executed only once.

To start using `datamigration` in your application, create a new file in your application directory called `datamigrations.go`. Register all migrations in the `init` function to ensure it is executed before the application starts processing requests. For example:

// cmd/myapp/datamigrations.go
package main

func init() {
	datamigration.MustRegister("register initial users", ...)
	// ...
	datamigration.MustRegister("create initial configuration entity", ...)
}

In order to register a new data migration:

1. register a new migration in `init` using `datamigration.MustRegister`,
2. build a new binary of your application and make sure all validators are running it,
3. send a transaction with `ExecuteMigrationMsg`, signed by required addresses,
4. if migration was executed, it became a part of the chain. Code of the migration must remain unchanged forever.

Each migration is registered for a specific chain.

Migration must be a pure function. Migration function must depend only on the data present in the context and database and not rely on non deterministic input (i.e. `time.Now` or `rand` package).

A registered migration must not be deleted or altered. This is mandatory in order for the state replying functionality.

Index

• Variables
• func MustRegister(migrationID string, m Migration)
• func NewExecutedMigrationBucket() orm.ModelBucket
• func RegisterQuery(qr weave.QueryRouter)
• func RegisterRoutes(r weave.Registry, auth x.Authenticator)
• type ExecuteMigrationMsg
  • func (*ExecuteMigrationMsg) Descriptor() ([]byte, []int)
  • func (m *ExecuteMigrationMsg) GetMetadata() *weave.Metadata
  • func (m *ExecuteMigrationMsg) GetMigrationID() string
  • func (m *ExecuteMigrationMsg) Marshal() (dAtA []byte, err error)
  • func (m *ExecuteMigrationMsg) MarshalTo(dAtA []byte) (int, error)
  • func (ExecuteMigrationMsg) Path() string
  • func (*ExecuteMigrationMsg) ProtoMessage()
  • func (m *ExecuteMigrationMsg) Reset()
  • func (m *ExecuteMigrationMsg) Size() (n int)
  • func (m *ExecuteMigrationMsg) String() string
  • func (m *ExecuteMigrationMsg) Unmarshal(dAtA []byte) error
  • func (msg *ExecuteMigrationMsg) Validate() error
  • func (m *ExecuteMigrationMsg) XXX_DiscardUnknown()
  • func (m *ExecuteMigrationMsg) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *ExecuteMigrationMsg) XXX_Merge(src proto.Message)
  • func (m *ExecuteMigrationMsg) XXX_Size() int
  • func (m *ExecuteMigrationMsg) XXX_Unmarshal(b []byte) error
• type ExecutedMigration
  • func (*ExecutedMigration) Descriptor() ([]byte, []int)
  • func (m *ExecutedMigration) GetMetadata() *weave.Metadata
  • func (m *ExecutedMigration) Marshal() (dAtA []byte, err error)
  • func (m *ExecutedMigration) MarshalTo(dAtA []byte) (int, error)
  • func (*ExecutedMigration) ProtoMessage()
  • func (m *ExecutedMigration) Reset()
  • func (m *ExecutedMigration) Size() (n int)
  • func (m *ExecutedMigration) String() string
  • func (m *ExecutedMigration) Unmarshal(dAtA []byte) error
  • func (em *ExecutedMigration) Validate() error
  • func (m *ExecutedMigration) XXX_DiscardUnknown()
  • func (m *ExecutedMigration) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *ExecutedMigration) XXX_Merge(src proto.Message)
  • func (m *ExecutedMigration) XXX_Size() int
  • func (m *ExecutedMigration) XXX_Unmarshal(b []byte) error
• type Migration

Variables

var (
	ErrInvalidLengthCodec = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowCodec   = fmt.Errorf("proto: integer overflow")
)

Functions

func MustRegister

func MustRegister(migrationID string, m Migration)

MustRegister registers an initialization function for given entity.

func NewExecutedMigrationBucket

func NewExecutedMigrationBucket() orm.ModelBucket

func RegisterQuery

func RegisterQuery(qr weave.QueryRouter)

func RegisterRoutes

func RegisterRoutes(r weave.Registry, auth x.Authenticator)

RegisterRoutes registers handlers for message processing.

Types

type ExecuteMigrationMsg

type ExecuteMigrationMsg struct {
	Metadata    *weave.Metadata `protobuf:"bytes,1,opt,name=metadata,proto3" json:"metadata,omitempty"`
	MigrationID string          `protobuf:"bytes,2,opt,name=migration_id,json=migrationId,proto3" json:"migration_id,omitempty"`
}

func (*ExecuteMigrationMsg) Descriptor

func (*ExecuteMigrationMsg) Descriptor() ([]byte, []int)

func (*ExecuteMigrationMsg) GetMetadata

func (m *ExecuteMigrationMsg) GetMetadata() *weave.Metadata

func (*ExecuteMigrationMsg) GetMigrationID

func (m *ExecuteMigrationMsg) GetMigrationID() string

func (*ExecuteMigrationMsg) Marshal

func (m *ExecuteMigrationMsg) Marshal() (dAtA []byte, err error)

func (*ExecuteMigrationMsg) MarshalTo

func (m *ExecuteMigrationMsg) MarshalTo(dAtA []byte) (int, error)

func (ExecuteMigrationMsg) Path

func (ExecuteMigrationMsg) Path() string

func (*ExecuteMigrationMsg) ProtoMessage

func (*ExecuteMigrationMsg) ProtoMessage()

func (*ExecuteMigrationMsg) Reset

func (m *ExecuteMigrationMsg) Reset()

func (*ExecuteMigrationMsg) Size

func (m *ExecuteMigrationMsg) Size() (n int)

func (*ExecuteMigrationMsg) String

func (m *ExecuteMigrationMsg) String() string

func (*ExecuteMigrationMsg) Unmarshal

func (m *ExecuteMigrationMsg) Unmarshal(dAtA []byte) error

func (*ExecuteMigrationMsg) Validate

func (msg *ExecuteMigrationMsg) Validate() error

func (*ExecuteMigrationMsg) XXX_DiscardUnknown

func (m *ExecuteMigrationMsg) XXX_DiscardUnknown()

func (*ExecuteMigrationMsg) XXX_Marshal

func (m *ExecuteMigrationMsg) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ExecuteMigrationMsg) XXX_Merge

func (m *ExecuteMigrationMsg) XXX_Merge(src proto.Message)

func (*ExecuteMigrationMsg) XXX_Size

func (m *ExecuteMigrationMsg) XXX_Size() int

func (*ExecuteMigrationMsg) XXX_Unmarshal

func (m *ExecuteMigrationMsg) XXX_Unmarshal(b []byte) error

type ExecutedMigration

type ExecutedMigration struct {
	Metadata *weave.Metadata `protobuf:"bytes,1,opt,name=metadata,proto3" json:"metadata,omitempty"`
}

func (*ExecutedMigration) Descriptor

func (*ExecutedMigration) Descriptor() ([]byte, []int)

func (*ExecutedMigration) GetMetadata

func (m *ExecutedMigration) GetMetadata() *weave.Metadata

func (*ExecutedMigration) Marshal

func (m *ExecutedMigration) Marshal() (dAtA []byte, err error)

func (*ExecutedMigration) MarshalTo

func (m *ExecutedMigration) MarshalTo(dAtA []byte) (int, error)

func (*ExecutedMigration) ProtoMessage

func (*ExecutedMigration) ProtoMessage()

func (*ExecutedMigration) Reset

func (m *ExecutedMigration) Reset()

func (*ExecutedMigration) Size

func (m *ExecutedMigration) Size() (n int)

func (*ExecutedMigration) String

func (m *ExecutedMigration) String() string

func (*ExecutedMigration) Unmarshal

func (m *ExecutedMigration) Unmarshal(dAtA []byte) error

func (*ExecutedMigration) Validate

func (em *ExecutedMigration) Validate() error

func (*ExecutedMigration) XXX_DiscardUnknown

func (m *ExecutedMigration) XXX_DiscardUnknown()

func (*ExecutedMigration) XXX_Marshal

func (m *ExecutedMigration) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ExecutedMigration) XXX_Merge

func (m *ExecutedMigration) XXX_Merge(src proto.Message)

func (*ExecutedMigration) XXX_Size

func (m *ExecutedMigration) XXX_Size() int

func (*ExecutedMigration) XXX_Unmarshal

func (m *ExecutedMigration) XXX_Unmarshal(b []byte) error

type Migration

type Migration struct {
	// RequiredSigners is a collection of at least one Address. Transaction
	// must be signed by all specified address owners in order for the
	// migration to authorized for execution.
	// This is configured in code and not on the chain in order to avoid
	// chicken-egg problem.
	RequiredSigners []weave.Address

	// ChainIDs specifies which chains this migration can be executed on.
	// This is helpful because no two chains are the same and therefore now
	// two chains should require the same set of data migrations. Usually
	// we run staging/testing/production setup, each maintaining a
	// different state.
	ChainIDs []string

	Migrate func(context.Context, weave.KVStore) error
}

Migration clubs together all requirements for executing a migration.