backends

package
v0.0.0-...-bb56650 Latest Latest
Warning

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

Go to latest
Published: Feb 20, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package backends provides common interfaces (Backend, Database, and Collection) and code for all backend implementations.

Design principles

  1. Interfaces are designed to balance the efficiency of individual backends and code duplication between them. For example, the `Collection.InsertAll` method creates a database and collection automatically if needed. Theoretically, the handler can make three separate backend calls (create a database if needed, create collection if needed, insert documents), but that implementation would likely be less efficient due to extra roundtrips, transactions, and/or locks. On the other hand, the logic of `ordered` `insert`s is only present in the handler. If some backend supports the same semantics as MongoDB, we will likely add a separate option method, and the handler would use that before falling back to the previous behavior.
  2. Backend objects are stateful. Database and Collection objects are stateless.
  3. Backends maintain the list of databases and collections. It is recommended that it does so by not querying the information_schema or equivalent often.
  4. Contexts are per-operation and should not be stored. They are used for passing authentication information via conninfo.
  5. Errors returned by methods could be nil, *Error, or some other opaque error type. *Error values can't be wrapped or be present anywhere in the error chain. Contracts enforce error codes; they are not documented in the code comments but are visible in the contract's code (to avoid duplication). Methods should return different error codes only if the difference is important for the handler.
  6. Passed parameters should not be modified because the handler may reuse them.

Testing

Backends are mainly tested through FerretDB's integration tests. But there are some common tests for all backends that check corner cases in contracts. They also test that all backends adjusted to contract changes.

Some backends may have their own tests.

Both kinds of tests could be removed over time as they are replaced by integration tests. Prefer integration tests when possible.

Index

Constants

View Source
const DefaultIndexName = "_id_"

DefaultIndexName is a name of the index that is created when a collection is created. This index defines document's primary key.

View Source
const ReservedPrefix = "_ferretdb_"

ReservedPrefix for names: databases, collections, schemas, tables, indexes, columns, etc.

Variables

This section is empty.

Functions

func ErrorCodeIs

func ErrorCodeIs(err error, code ErrorCode, codes ...ErrorCode) bool

ErrorCodeIs returns true if err is *Error with one of the given error codes.

At least one error code must be given.

Types

type Backend

type Backend interface {
	Close()

	Status(context.Context, *StatusParams) (*StatusResult, error)

	Database(string) (Database, error)
	ListDatabases(context.Context, *ListDatabasesParams) (*ListDatabasesResult, error)
	DropDatabase(context.Context, *DropDatabaseParams) error

	prometheus.Collector
}

Backend is a generic interface for all backends for accessing them.

Backend object should be stateful and wrap database connection(s). Handler uses only one long-lived Backend object.

Backend(s) methods can be called by multiple client connections / command handlers concurrently. They should be thread-safe.

See backendContract and its methods for additional details.

func BackendContract

func BackendContract(b Backend) Backend

BackendContract wraps Backend and enforces its contract.

All backend implementations should use that function when they create new Backend instances. The handler should not use that function.

See backendContract and its methods for additional details.

type Collection

Collection is a generic interface for all backends for accessing collection.

Collection object should be stateless and temporary; all state should be in the Backend that created Database instance that created this Collection instance. Handler can create and destroy Collection objects on the fly. Creating a Collection object does not imply the creation of the database or collection.

Collection methods should be thread-safe.

See collectionContract and its methods for additional details.

func CollectionContract

func CollectionContract(c Collection) Collection

CollectionContract wraps Collection and enforces its contract.

All backend implementations should use that function when they create new Collection instances. The handler should not use that function.

See collectionContract and its methods for additional details.

type CollectionInfo

type CollectionInfo struct {
	Name            string
	UUID            string
	CappedSize      int64
	CappedDocuments int64
	// contains filtered or unexported fields
}

CollectionInfo represents information about a single collection.

func (*CollectionInfo) Capped

func (ci *CollectionInfo) Capped() bool

Capped returns true if collection is capped.

type CollectionStatsParams

type CollectionStatsParams struct {
	Refresh bool
}

CollectionStatsParams represents the parameters of Collection.Stats method.

type CollectionStatsResult

type CollectionStatsResult struct {
	CountDocuments  int64
	SizeTotal       int64
	SizeIndexes     int64
	SizeCollection  int64
	SizeFreeStorage int64
	IndexSizes      []IndexSize
}

CollectionStatsResult represents the results of Collection.Stats method.

type CompactParams

type CompactParams struct {
	Full bool
}

CompactParams represents the parameters of Collection.Compact method.

type CompactResult

type CompactResult struct{}

CompactResult represents the results of Collection.Compact method.

type CreateCollectionParams

type CreateCollectionParams struct {
	Name            string
	CappedSize      int64
	CappedDocuments int64
	// contains filtered or unexported fields
}

CreateCollectionParams represents the parameters of Database.CreateCollection method.

func (*CreateCollectionParams) Capped

func (ccp *CreateCollectionParams) Capped() bool

Capped returns true if capped collection creation is requested.

type CreateIndexesParams

type CreateIndexesParams struct {
	Indexes []IndexInfo
}

CreateIndexesParams represents the parameters of Collection.CreateIndexes method.

type CreateIndexesResult

type CreateIndexesResult struct{}

CreateIndexesResult represents the results of Collection.CreateIndexes method.

type Database

Database is a generic interface for all backends for accessing databases.

Database object should be stateless and temporary; all state should be in the Backend that created this Database instance. Handler can create and destroy Database objects on the fly. Creating a Database object does not imply the creation of the database.

Database methods should be thread-safe.

See databaseContract and its methods for additional details.

func DatabaseContract

func DatabaseContract(db Database) Database

DatabaseContract wraps Database and enforces its contract.

All backend implementations should use that function when they create new Database instances. The handler should not use that function.

See databaseContract and its methods for additional details.

type DatabaseInfo

type DatabaseInfo struct {
	Name string
}

DatabaseInfo represents information about a single database.

type DatabaseStatsParams

type DatabaseStatsParams struct {
	Refresh bool
}

DatabaseStatsParams represents the parameters of Database.Stats method.

type DatabaseStatsResult

type DatabaseStatsResult struct {
	CountDocuments  int64
	SizeTotal       int64
	SizeIndexes     int64
	SizeCollections int64
	SizeFreeStorage int64
}

DatabaseStatsResult represents the results of Database.Stats method.

type DeleteAllParams

type DeleteAllParams struct {
	IDs       []any
	RecordIDs []int64
}

DeleteAllParams represents the parameters of Collection.Delete method.

type DeleteAllResult

type DeleteAllResult struct {
	Deleted int32
}

DeleteAllResult represents the results of Collection.Delete method.

type DropCollectionParams

type DropCollectionParams struct {
	Name string
}

DropCollectionParams represents the parameters of Database.DropCollection method.

type DropDatabaseParams

type DropDatabaseParams struct {
	Name string
}

DropDatabaseParams represents the parameters of Backend.DropDatabase method.

type DropIndexesParams

type DropIndexesParams struct {
	Indexes []string
}

DropIndexesParams represents the parameters of Collection.DropIndexes method.

type DropIndexesResult

type DropIndexesResult struct{}

DropIndexesResult represents the results of Collection.DropIndexes method.

type Error

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

Error represents a backend error returned by all Backend, Database and Collection methods.

func NewError

func NewError(code ErrorCode, err error) *Error

NewError creates a new backend error.

Code must not be 0. Err may be nil.

func (*Error) Code

func (err *Error) Code() ErrorCode

Code returns the error code.

func (*Error) Error

func (err *Error) Error() string

Error implements error interface.

type ErrorCode

type ErrorCode int

ErrorCode represent a backend error code.

const (
	ErrorCodeDatabaseNameIsInvalid ErrorCode
	ErrorCodeDatabaseDoesNotExist

	ErrorCodeCollectionNameIsInvalid
	ErrorCodeCollectionDoesNotExist
	ErrorCodeCollectionAlreadyExists

	ErrorCodeInsertDuplicateID
)

Error codes.

func (ErrorCode) String

func (i ErrorCode) String() string

type ExplainParams

type ExplainParams struct {
	Filter *types.Document
	Sort   *types.Document
	Limit  int64
}

ExplainParams represents the parameters of Collection.Explain method.

type ExplainResult

type ExplainResult struct {
	QueryPlanner   *types.Document
	FilterPushdown bool
	SortPushdown   bool
	LimitPushdown  bool
}

ExplainResult represents the results of Collection.Explain method.

type IndexInfo

type IndexInfo struct {
	Name   string
	Key    []IndexKeyPair
	Unique bool
}

IndexInfo represents information about a single index.

type IndexKeyPair

type IndexKeyPair struct {
	Field      string
	Descending bool
}

IndexKeyPair consists of a field name and a sort order that are part of the index.

type IndexSize

type IndexSize struct {
	Name string
	Size int64
}

IndexSize represents the name and the size of an index.

type InsertAllParams

type InsertAllParams struct {
	Docs []*types.Document
}

InsertAllParams represents the parameters of Collection.InsertAll method.

type InsertAllResult

type InsertAllResult struct{}

InsertAllResult represents the results of Collection.InsertAll method.

type ListCollectionsParams

type ListCollectionsParams struct {
	Name string // TODO https://github.com/FerretDB/FerretDB/issues/3601
}

ListCollectionsParams represents the parameters of Database.ListCollections method.

type ListCollectionsResult

type ListCollectionsResult struct {
	Collections []CollectionInfo
}

ListCollectionsResult represents the results of Database.ListCollections method.

type ListDatabasesParams

type ListDatabasesParams struct {
	Name string // TODO https://github.com/FerretDB/FerretDB/issues/3601
}

ListDatabasesParams represents the parameters of Backend.ListDatabases method.

type ListDatabasesResult

type ListDatabasesResult struct {
	Databases []DatabaseInfo
}

ListDatabasesResult represents the results of Backend.ListDatabases method.

type ListIndexesParams

type ListIndexesParams struct{}

ListIndexesParams represents the parameters of Collection.ListIndexes method.

type ListIndexesResult

type ListIndexesResult struct {
	Indexes []IndexInfo
}

ListIndexesResult represents the results of Collection.ListIndexes method.

type QueryParams

type QueryParams struct {
	Filter *types.Document
	Sort   *types.Document
	Limit  int64

	OnlyRecordIDs bool
	Comment       string
}

QueryParams represents the parameters of Collection.Query method.

type QueryResult

type QueryResult struct {
	Iter types.DocumentsIterator
}

QueryResult represents the results of Collection.Query method.

type RenameCollectionParams

type RenameCollectionParams struct {
	OldName string
	NewName string
}

RenameCollectionParams represents the parameters of Database.RenameCollection method.

type StatusParams

type StatusParams struct{}

StatusParams represents the parameters of Backend.Status method.

type StatusResult

type StatusResult struct {
	CountCollections       int64
	CountCappedCollections int32
}

StatusResult represents the results of Backend.Status method.

type UpdateAllParams

type UpdateAllParams struct {
	Docs []*types.Document
}

UpdateAllParams represents the parameters of Collection.Update method.

type UpdateAllResult

type UpdateAllResult struct {
	Updated int32
}

UpdateAllResult represents the results of Collection.Update method.

Directories

Path Synopsis
decorators
dummy
Package dummy provides decorators that delegate all methods to wrapped objects.
Package dummy provides decorators that delegate all methods to wrapped objects.
oplog
Package oplog provides decorators that add OpLog functionality to the backend.
Package oplog provides decorators that add OpLog functionality to the backend.
Package hana provides backend for SAP HANA.
Package hana provides backend for SAP HANA.
Package mysql provides backend for MySQL and compatible databases.
Package mysql provides backend for MySQL and compatible databases.
metadata
Package metadata provides access to databases and collections information.
Package metadata provides access to databases and collections information.
metadata/pool
Package pool provides access to MySQL connections.
Package pool provides access to MySQL connections.
Package postgresql provides backend for PostgreSQL and compatible databases.
Package postgresql provides backend for PostgreSQL and compatible databases.
metadata
Package metadata provides access to databases and collections information.
Package metadata provides access to databases and collections information.
metadata/pool
Package pool provides access to PostgreSQL connections.
Package pool provides access to PostgreSQL connections.
Package sqlite provides SQLite backend.
Package sqlite provides SQLite backend.
metadata
Package metadata provides access to databases and collections information.
Package metadata provides access to databases and collections information.
metadata/pool
Package pool provides access to SQLite databases and their connections.
Package pool provides access to SQLite databases and their connections.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL