database

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2021 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package database provides database primitives such as tables, transactions and indexes.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrTableNotFound is returned when the targeted table doesn't exist.
	ErrTableNotFound = errors.New("table not found")

	// ErrTableAlreadyExists is returned when attempting to create a table with the
	// same name as an existing one.
	ErrTableAlreadyExists = errors.New("table already exists")

	// ErrIndexNotFound is returned when the targeted index doesn't exist.
	ErrIndexNotFound = errors.New("index not found")

	// ErrIndexAlreadyExists is returned when attempting to create an index with the
	// same name as an existing one.
	ErrIndexAlreadyExists = errors.New("index already exists")

	// ErrDocumentNotFound is returned when no document is associated with the provided key.
	ErrDocumentNotFound = errors.New("document not found")

	// ErrDuplicateDocument is returned when another document is already associated with a given key, primary key,
	// or if there is a unique index violation.
	ErrDuplicateDocument = errors.New("duplicate document")
)
View Source 
var (
	// ErrIndexDuplicateValue is returned when a value is already associated with a key
	ErrIndexDuplicateValue = errors.New("duplicate value")

	// ErrIndexWrongArity is returned when trying to index more values that what an
	// index supports.
	ErrIndexWrongArity = errors.New("wrong index arity")
)

Functions

func CastConversion added in v0.12.0 

func CastConversion(v document.Value, path document.Path, targetType document.ValueType) (document.Value, error)

CastConversion is a ConversionFunc that casts the value to the target type.

func LosslessNumbersConversion added in v0.12.0 

func LosslessNumbersConversion(v document.Value, path document.Path, targetType document.ValueType) (document.Value, error)

LosslessConversion is a ConversionFunc that only converts numbers if there is no precision loss in the process.

Types

type Catalog added in v0.11.0 

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

Catalog holds all table and index informations.

func NewCatalog added in v0.11.0 

func NewCatalog() *Catalog

func (*Catalog) AddFieldConstraint added in v0.11.0 

func (c *Catalog) AddFieldConstraint(tx *Transaction, tableName string, fc FieldConstraint) error

AddFieldConstraint adds a field constraint to a table.

func (*Catalog) Clone added in v0.11.0 

func (c *Catalog) Clone() *Catalog

Clone the catalog. Mostly used for testing purposes.

func (*Catalog) CreateIndex added in v0.11.0 

func (c *Catalog) CreateIndex(tx *Transaction, opts *IndexInfo) error

CreateIndex creates an index with the given name. If it already exists, returns ErrIndexAlreadyExists.

func (*Catalog) CreateTable added in v0.11.0 

func (c *Catalog) CreateTable(tx *Transaction, tableName string, info *TableInfo) error

CreateTable creates a table with the given name. If it already exists, returns ErrTableAlreadyExists.

func (*Catalog) DropIndex added in v0.11.0 

func (c *Catalog) DropIndex(tx *Transaction, name string) error

DropIndex deletes an index from the database.

func (*Catalog) DropTable added in v0.11.0 

func (c *Catalog) DropTable(tx *Transaction, tableName string) error

DropTable deletes a table from the database.

func (*Catalog) GetIndex added in v0.11.0 

func (c *Catalog) GetIndex(tx *Transaction, indexName string) (*Index, error)

GetIndex returns an index by name.

func (*Catalog) GetTable added in v0.11.0 

func (c *Catalog) GetTable(tx *Transaction, tableName string) (*Table, error)

func (*Catalog) ListIndexes added in v0.11.0 

func (c *Catalog) ListIndexes(tableName string) []string

ListIndexes returns an index by name.

func (*Catalog) Load added in v0.11.0 

func (c *Catalog) Load(tx *Transaction) error

func (*Catalog) ReIndex added in v0.11.0 

func (c *Catalog) ReIndex(tx *Transaction, indexName string) error

ReIndex truncates and recreates selected index from scratch.

func (*Catalog) ReIndexAll added in v0.11.0 

func (c *Catalog) ReIndexAll(tx *Transaction) error

ReIndexAll truncates and recreates all indexes of the database from scratch.

func (*Catalog) RenameTable added in v0.11.0 

func (c *Catalog) RenameTable(tx *Transaction, oldName, newName string) error

RenameTable renames a table. If it doesn't exist, it returns ErrTableNotFound.

type ConversionFunc added in v0.12.0 

type ConversionFunc func(v document.Value, path document.Path, targetType document.ValueType) (document.Value, error)

ConversionFunc is called when the type of a value is different than the expected type and the value needs to be converted.

type Database 

type Database struct {

	// Codec used to encode documents. Defaults to MessagePack.
	Codec encoding.Codec
	// contains filtered or unexported fields
}

A Database manages a list of tables in an engine.

func New 

func New(ctx context.Context, ng engine.Engine, opts Options) (*Database, error)

New initializes the DB using the given engine.

func (*Database) Begin 

func (db *Database) Begin(writable bool) (*Transaction, error)

Begin starts a new transaction with default options. The returned transaction must be closed either by calling Rollback or Commit.

func (*Database) BeginTx added in v0.8.0 

func (db *Database) BeginTx(ctx context.Context, opts *TxOptions) (*Transaction, error)

BeginTx starts a new transaction with the given options. If opts is empty, it will use the default options. The returned transaction must be closed either by calling Rollback or Commit. If the Attached option is passed, it opens a database level transaction, which gets attached to the database and prevents any other transaction to be opened afterwards until it gets rolled back or commited.

func (*Database) Catalog added in v0.11.0 

func (db *Database) Catalog() *Catalog

func (*Database) Close 

func (db *Database) Close() error

Close the underlying engine.

func (*Database) GetAttachedTx added in v0.8.0 

func (db *Database) GetAttachedTx() *Transaction

GetAttachedTx returns the transaction attached to the database. It returns nil if there is no such transaction. The returned transaction is not thread safe.

type FieldConstraint 

type FieldConstraint struct {
	Path         document.Path
	Type         document.ValueType
	IsPrimaryKey bool
	IsNotNull    bool
	IsUnique     bool // not stored, only set during table creation
	DefaultValue document.Value
	IsInferred   bool
	InferredBy   []document.Path
}

FieldConstraint describes constraints on a particular field.

func (*FieldConstraint) HasDefaultValue added in v0.9.0 

func (f *FieldConstraint) HasDefaultValue() bool

HasDefaultValue returns this field contains a default value constraint.

func (*FieldConstraint) IsEqual added in v0.11.0 

func (f *FieldConstraint) IsEqual(other *FieldConstraint) (bool, error)

IsEqual compares f with other member by member. Inference is not compared.

func (*FieldConstraint) MergeInferred added in v0.11.0 

func (f *FieldConstraint) MergeInferred(other *FieldConstraint)

MergeInferred adds the other.InferredBy to f.InferredBy and ensures there are no duplicates.

func (*FieldConstraint) ScanDocument 

func (f *FieldConstraint) ScanDocument(d document.Document) error

ScanDocument implements the document.Scanner interface.

func (*FieldConstraint) String added in v0.11.0 

func (f *FieldConstraint) String() string

func (*FieldConstraint) ToDocument 

func (f *FieldConstraint) ToDocument() document.Document

ToDocument returns a document from f.

type FieldConstraints added in v0.9.0 

type FieldConstraints []*FieldConstraint

FieldConstraints is a list of field constraints.

func NewFieldConstraints added in v0.11.0 

func NewFieldConstraints(userConstraints []*FieldConstraint) (FieldConstraints, error)

NewFieldConstraints takes user-defined field constraints, validates them, infers additional constraints if needed, and returns a valid FieldConstraints type that can be assigned to a table.

func (*FieldConstraints) Add added in v0.11.0 

func (f *FieldConstraints) Add(newFc *FieldConstraint) error

Add a field constraint to the list. If another constraint exists for the same path and they are equal, newFc will be ignored. Otherwise an error will be returned. If newFc has been inferred by another constraint and another constraint exists with the same path, their InferredBy member will be merged.

func (FieldConstraints) ConvertDocument added in v0.11.0 

func (f FieldConstraints) ConvertDocument(d document.Document) (*document.FieldBuffer, error)

ConvertDocument the document using the field constraints. It converts any path that has a field constraint on it into the specified type using CAST. If there is no constraint on an integer field or value, it converts it into a double. Default values on missing fields are not applied.

func (FieldConstraints) ConvertValueAtPath added in v0.12.0 

func (f FieldConstraints) ConvertValueAtPath(path document.Path, v document.Value, conversionFn ConversionFunc) (document.Value, error)

ConvertValueAtPath converts the value using the field constraints that are applicable at the given path.

func (FieldConstraints) Get added in v0.12.0 

func (f FieldConstraints) Get(path document.Path) *FieldConstraint

Get a field constraint by path. Returns nil if not found.

func (FieldConstraints) Infer added in v0.11.0 

func (f FieldConstraints) Infer() (FieldConstraints, error)

Infer additional constraints based on user defined ones. For example, given the following table: 

CREATE TABLE foo (a.b[0] TEXT)

this function will return a TableInfo that behaves as if the table had been created like this: 

CREATE TABLE foo(
   a DOCUMENT
   a.b ARRAY
   a.b[0] TEXT
)

func (FieldConstraints) ValidateDocument added in v0.9.0 

func (f FieldConstraints) ValidateDocument(d document.Document) (*document.FieldBuffer, error)

ValidateDocument calls Convert then ensures the document validates against the field constraints.

type Index 

type Index struct {
	Info *IndexInfo
	// contains filtered or unexported fields
}

An Index associates encoded values with keys.

The association is performed by encoding the values in a binary format that preserve ordering when compared lexicographically. For the implementation, see the binarysort package and the document.ValueEncoder.

func NewIndex added in v0.11.0 

func NewIndex(tx engine.Transaction, idxName string, opts *IndexInfo) *Index

NewIndex creates an index that associates values with a list of keys.

func (*Index) Arity added in v0.12.0 

func (idx *Index) Arity() int

Arity returns how many values the index is operating on. For example, an index created with `CREATE INDEX idx_a_b ON foo (a, b)` has an arity of 2.

func (*Index) AscendGreaterOrEqual added in v0.11.0 

func (idx *Index) AscendGreaterOrEqual(pivot Pivot, fn func(val, key []byte) error) error

AscendGreaterOrEqual seeks for the pivot and then goes through all the subsequent key value pairs in increasing order and calls the given function for each pair. If the given function returns an error, the iteration stops and returns that error. If the pivot(s) is/are empty, starts from the beginning.

Valid pivots are: - zero value pivot

  • iterate on everything

- n elements pivot (where n is the index arity) with each element having a value and a type

  • iterate starting at the closest index value
  • optionally, the last pivot element can have just a type and no value, which will scope the value of that element to that type

- less than n elements pivot, with each element having a value and a type

  • iterate starting at the closest index value, using the first known value for missing elements
  • optionally, the last pivot element can have just a type and no value, which will scope the value of that element to that type

- a single element with a type but nil value: will iterate on everything of that type

Any other variation of a pivot are invalid and will panic.

func (*Index) Delete added in v0.11.0 

func (idx *Index) Delete(vs []document.Value, k []byte) error

Delete all the references to the key from the index.

func (*Index) DescendLessOrEqual added in v0.11.0 

func (idx *Index) DescendLessOrEqual(pivot Pivot, fn func(val, key []byte) error) error

DescendLessOrEqual seeks for the pivot and then goes through all the subsequent key value pairs in descreasing order and calls the given function for each pair. If the given function returns an error, the iteration stops and returns that error. If the pivot(s) is/are empty, starts from the end.

Valid pivots are: - zero value pivot

  • iterate on everything

- n elements pivot (where n is the index arity) with each element having a value and a type

  • iterate starting at the closest index value
  • optionally, the last pivot element can have just a type and no value, which will scope the value of that element to that type

- less than n elements pivot, with each element having a value and a type

  • iterate starting at the closest index value, using the last known value for missing elements
  • optionally, the last pivot element can have just a type and no value, which will scope the value of that element to that type

- a single element with a type but nil value: will iterate on everything of that type

Any other variation of a pivot are invalid and will panic.

func (*Index) EncodeValueBuffer added in v0.12.0 

func (idx *Index) EncodeValueBuffer(vb *document.ValueBuffer) ([]byte, error)

EncodeValueBuffer encodes the value buffer containing a single or multiple values being indexed into a byte array, keeping the order of the original values.

The values are marshalled and separated with a document.ArrayValueDelim, *without* a trailing document.ArrayEnd, which enables to handle cases where only some of the values are being provided and still perform lookups (like index_foo_a_b_c and providing only a and b).

See IndexValueEncoder for details about how the value themselves are encoded.

func (*Index) IsComposite added in v0.12.0 

func (idx *Index) IsComposite() bool

IsComposite returns true if the index is defined to operate on at least more than one value.

func (*Index) Set added in v0.11.0 

func (idx *Index) Set(vs []document.Value, k []byte) error

Set associates values with a key. If Unique is set to false, it is possible to associate multiple keys for the same value but a key can be associated to only one value.

func (*Index) Truncate added in v0.11.0 

func (idx *Index) Truncate() error

Truncate deletes all the index data.

type IndexInfo added in v0.11.0 

type IndexInfo struct {
	TableName string
	IndexName string
	Paths     []document.Path

	// If set to true, values will be associated with at most one key. False by default.
	Unique bool

	// If set, the index is typed and only accepts values of those types.
	Types []document.ValueType
}

IndexInfo holds the configuration of an index.

func (IndexInfo) Clone added in v0.11.0 

func (i IndexInfo) Clone() *IndexInfo

Clone returns a copy of the index information.

func (*IndexInfo) ScanDocument added in v0.11.0 

func (i *IndexInfo) ScanDocument(d document.Document) error

ScanDocument implements the document.Scanner interface.

func (*IndexInfo) ToDocument added in v0.11.0 

func (i *IndexInfo) ToDocument() document.Document

ToDocument creates a document from an IndexConfig.

type Indexes added in v0.11.0 

type Indexes []*Index

func (Indexes) GetIndex added in v0.11.0 

func (i Indexes) GetIndex(name string) *Index

func (Indexes) GetIndexByPath added in v0.11.0 

func (i Indexes) GetIndexByPath(p document.Path) *Index

type Options added in v0.8.0 

type Options struct {
	Codec encoding.Codec
}

type Pivot added in v0.12.0 

type Pivot []document.Value

func (Pivot) IsAny added in v0.12.0 

func (pivot Pivot) IsAny() bool

IsAny return true if every value of the pivot is typed with AnyType

type Table 

type Table struct {
	Store engine.Store
	// contains filtered or unexported fields
}

A Table represents a collection of documents.

func (*Table) AscendGreaterOrEqual added in v0.10.0 

func (t *Table) AscendGreaterOrEqual(pivot document.Value, fn func(d document.Document) error) error

AscendGreaterOrEqual iterates over the documents of the table whose key is greater than or equal to the pivot. The pivot is converted to the type of the primary key, if any, prior to iteration. If the pivot is empty, it iterates from the beginning of the table.

func (*Table) Delete 

func (t *Table) Delete(key []byte) error

Delete a document by key. Indexes are automatically updated.

func (*Table) DescendLessOrEqual added in v0.10.0 

func (t *Table) DescendLessOrEqual(pivot document.Value, fn func(d document.Document) error) error

DescendLessOrEqual iterates over the documents of the table whose key is less than or equal to the pivot, in reverse order. The pivot is converted to the type of the primary key, if any, prior to iteration. If the pivot is empty, it iterates from the end of the table in reverse order.

func (*Table) EncodeValue added in v0.11.0 

func (t *Table) EncodeValue(v document.Value) ([]byte, error)

EncodeValue encodes a value following primary key constraints. It returns a binary representation of the key as used in the store. It can be used to manually add a new entry to the store or to compare with other keys during table iteration.

func (*Table) GetDocument 

func (t *Table) GetDocument(key []byte) (document.Document, error)

GetDocument returns one document by key.

func (*Table) Indexes 

func (t *Table) Indexes() Indexes

Indexes returns the list of indexes of this table. Returned Indexes may not represent the most up to date data. Always get a fresh Table instance before calling this method.

func (*Table) Info added in v0.7.0 

func (t *Table) Info() *TableInfo

Info returns table information. Returned TableInfo may not represent the most up to date data. Always get a fresh Table instance before calling this method.

func (*Table) Insert 

func (t *Table) Insert(d document.Document) (document.Document, error)

Insert the document into the table. If a primary key has been specified during the table creation, the field is expected to be present in the given document. If no primary key has been selected, a monotonic autoincremented integer key will be generated. It returns the inserted document alongside its key. They key can be accessed using the document.Keyer interface.

func (*Table) Iterate 

func (t *Table) Iterate(fn func(d document.Document) error) error

Iterate goes through all the documents of the table and calls the given function by passing each one of them. If the given function returns an error, the iteration stops.

func (*Table) Name added in v0.7.0 

func (t *Table) Name() string

Name returns the name of the table.

func (*Table) Replace 

func (t *Table) Replace(key []byte, d document.Document) error

Replace a document by key. An error is returned if the key doesn't exist. Indexes are automatically updated.

func (*Table) Truncate 

func (t *Table) Truncate() error

Truncate deletes all the documents from the table.

func (*Table) Tx added in v0.8.0 

func (t *Table) Tx() *Transaction

Tx returns the current transaction.

type TableInfo added in v0.7.0 

type TableInfo struct {
	FieldConstraints FieldConstraints
	// contains filtered or unexported fields
}

TableInfo contains information about a table.

func (*TableInfo) Clone added in v0.11.0 

func (ti *TableInfo) Clone() *TableInfo

Clone creates another tableInfo with the same values.

func (*TableInfo) GetPrimaryKey added in v0.7.0 

func (ti *TableInfo) GetPrimaryKey() *FieldConstraint

GetPrimaryKey returns the field constraint of the primary key. Returns nil if there is no primary key.

func (*TableInfo) ScanDocument added in v0.7.0 

func (ti *TableInfo) ScanDocument(d document.Document) error

ScanDocument decodes d into ti.

func (*TableInfo) ToDocument added in v0.7.0 

func (ti *TableInfo) ToDocument() document.Document

ToDocument turns ti into a document.

type Transaction 

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

Transaction represents a database transaction. It provides methods for managing the collection of tables and the transaction itself. Transaction is either read-only or read/write. Read-only can be used to read tables and read/write can be used to read, create, delete and modify tables.

func (*Transaction) AddFieldConstraint added in v0.11.0 

func (tx *Transaction) AddFieldConstraint(tableName string, fc FieldConstraint) error

AddFieldConstraint adds a field constraint to a table.

func (*Transaction) Commit 

func (tx *Transaction) Commit() error

Commit the transaction. Calling this method on read-only transactions will return an error.

func (*Transaction) CreateIndex 

func (tx *Transaction) CreateIndex(opts *IndexInfo) error

CreateIndex creates an index with the given name. If it already exists, returns ErrIndexAlreadyExists.

func (*Transaction) CreateTable 

func (tx *Transaction) CreateTable(name string, info *TableInfo) error

CreateTable creates a table with the given name. If it already exists, returns ErrTableAlreadyExists.

func (*Transaction) DB added in v0.8.0 

func (tx *Transaction) DB() *Database

DB returns the underlying database that created the transaction.

func (*Transaction) DropIndex 

func (tx *Transaction) DropIndex(name string) error

DropIndex deletes an index from the database.

func (*Transaction) DropTable 

func (tx *Transaction) DropTable(name string) error

DropTable deletes a table from the database.

func (*Transaction) GetIndex 

func (tx *Transaction) GetIndex(name string) (*Index, error)

GetIndex returns an index by name.

func (*Transaction) GetTable 

func (tx *Transaction) GetTable(name string) (*Table, error)

GetTable returns a table by name. The table instance is only valid for the lifetime of the transaction.

func (*Transaction) ListIndexes 

func (tx *Transaction) ListIndexes() []string

ListIndexes lists all indexes.

func (*Transaction) ReIndex 

func (tx *Transaction) ReIndex(indexName string) error

ReIndex truncates and recreates selected index from scratch.

func (*Transaction) ReIndexAll 

func (tx *Transaction) ReIndexAll() error

ReIndexAll truncates and recreates all indexes of the database from scratch.

func (*Transaction) RenameTable added in v0.7.0 

func (tx *Transaction) RenameTable(oldName, newName string) error

RenameTable renames a table. If it doesn't exist, it returns ErrTableNotFound.

func (*Transaction) Rollback 

func (tx *Transaction) Rollback() error

Rollback the transaction. Can be used safely after commit.

func (*Transaction) Writable 

func (tx *Transaction) Writable() bool

Writable indicates if the transaction is writable or not.

type TxOptions added in v0.8.0 

type TxOptions struct {
	// Open a read-only transaction.
	ReadOnly bool
	// Set the transaction as global at the database level.
	// Any queries run by the database will use that transaction until it is
	// rolled back or commited.
	Attached bool
}

TxOptions are passed to Begin to configure transactions.

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.