backends

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.

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
• func ErrorCodeIs(err error, code ErrorCode, codes ...ErrorCode) bool
• type Backend
  • func BackendContract(b Backend) Backend
• type Collection
  • func CollectionContract(c Collection) Collection
• type CollectionInfo
  • func (ci *CollectionInfo) Capped() bool
• type CollectionStatsParams
• type CollectionStatsResult
• type CompactParams
• type CompactResult
• type CreateCollectionParams
  • func (ccp *CreateCollectionParams) Capped() bool
• type CreateIndexesParams
• type CreateIndexesResult
• type Database
  • func DatabaseContract(db Database) Database
• type DatabaseInfo
• type DatabaseStatsParams
• type DatabaseStatsResult
• type DeleteAllParams
• type DeleteAllResult
• type DropCollectionParams
• type DropDatabaseParams
• type DropIndexesParams
• type DropIndexesResult
• type Error
  • func NewError(code ErrorCode, err error) *Error
  • func (err *Error) Code() ErrorCode
  • func (err *Error) Error() string
• type ErrorCode
  • func (i ErrorCode) String() string
• type ExplainParams
• type ExplainResult
• type IndexInfo
• type IndexKeyPair
• type InsertAllParams
• type InsertAllResult
• type ListCollectionsParams
• type ListCollectionsResult
• type ListDatabasesParams
• type ListDatabasesResult
• type ListIndexesParams
• type ListIndexesResult
• type QueryParams
• type QueryResult
• type RenameCollectionParams
• type StatusParams
• type StatusResult
• type UpdateAllParams
• type UpdateAllResult

Constants

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.

const ReservedPrefix = "_ferretdb_"

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

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()

	Name() string
	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

type Collection interface {
	Query(context.Context, *QueryParams) (*QueryResult, error)
	InsertAll(context.Context, *InsertAllParams) (*InsertAllResult, error)
	UpdateAll(context.Context, *UpdateAllParams) (*UpdateAllResult, error)
	DeleteAll(context.Context, *DeleteAllParams) (*DeleteAllResult, error)
	Explain(context.Context, *ExplainParams) (*ExplainResult, error)

	Stats(context.Context, *CollectionStatsParams) (*CollectionStatsResult, error)
	Compact(context.Context, *CompactParams) (*CompactResult, error)

	ListIndexes(context.Context, *ListIndexesParams) (*ListIndexesResult, error)
	CreateIndexes(context.Context, *CreateIndexesParams) (*CreateIndexesResult, error)
	DropIndexes(context.Context, *DropIndexesParams) (*DropIndexesResult, error)
}

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
	CappedSize      int64 // TODO https://github.com/FerretDB/FerretDB/issues/3458
	CappedDocuments int64 // TODO https://github.com/FerretDB/FerretDB/issues/3458
}

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 // TODO https://github.com/FerretDB/FerretDB/issues/3518
}

CollectionStatsParams represents the parameters of Collection.Stats method.

type CollectionStatsResult

type CollectionStatsResult struct {
	CountObjects   int64
	CountIndexes   int64
	SizeTotal      int64
	SizeIndexes    int64
	SizeCollection int64
}

CollectionStatsResult represents the results of Collection.Stats method.

CountObjects is an estimate of the number of documents.

TODO https://github.com/FerretDB/FerretDB/issues/2447

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 // TODO https://github.com/FerretDB/FerretDB/issues/3458
	CappedDocuments int64 // TODO https://github.com/FerretDB/FerretDB/issues/3458
}

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

type Database interface {
	Collection(string) (Collection, error)
	ListCollections(context.Context, *ListCollectionsParams) (*ListCollectionsResult, error)
	CreateCollection(context.Context, *CreateCollectionParams) error
	DropCollection(context.Context, *DropCollectionParams) error
	RenameCollection(context.Context, *RenameCollectionParams) error

	Stats(context.Context, *DatabaseStatsParams) (*DatabaseStatsResult, error)
}

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
	Size int64
}

DatabaseInfo represents information about a single database.

type DatabaseStatsParams

type DatabaseStatsParams struct {
	Refresh bool // TODO https://github.com/FerretDB/FerretDB/issues/3518
}

DatabaseStatsParams represents the parameters of Database.Stats method.

type DatabaseStatsResult

type DatabaseStatsResult struct {
	CountCollections int64
	CountObjects     int64
	CountIndexes     int64
	SizeTotal        int64
	SizeIndexes      int64
	SizeCollections  int64
}

DatabaseStatsResult represents the results of Database.Stats method.

CountObjects is an estimate of the number of documents.

TODO https://github.com/FerretDB/FerretDB/issues/2447

type DeleteAllParams

type DeleteAllParams struct {
	IDs       []any
	RecordIDs []types.Timestamp
}

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 {
	// TODO https://github.com/FerretDB/FerretDB/issues/3235
	Filter *types.Document
}

ExplainParams represents the parameters of Collection.Explain method.

type ExplainResult

type ExplainResult struct {
	QueryPlanner *types.Document
	// TODO https://github.com/FerretDB/FerretDB/issues/3235
	QueryPushdown 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 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{}

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{}

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 {
	// TODO https://github.com/FerretDB/FerretDB/issues/3235
	Filter        *types.Document
	OnlyRecordIDs bool // TODO https://github.com/FerretDB/FerretDB/issues/3490
}

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
}

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.