backends

Documentation

Overview

Package backends provides common interfaces and code for all backend implementations.

Design principles.

1. Interfaces are relatively high-level and "fat" (or not). We are generally doing one backend interface call per handler call. For example, `insert` command handler calls only `db.Database("database").Collection("collection").Insert(ctx, params)` method that would create a database if needed, create a collection if needed, and insert all documents with correct parameters. There is no method to insert one document into an existing collection. That shifts some complexity from a single handler into multiple backend implementations; for example, support for `insert` with `ordered: true` and `ordered: false` should be implemented multiple times. But that allows those implementations to be much more effective.
2. Backend objects are stateful. Database objects are almost stateless but should be Close()'d to avoid connection leaks. Collection objects are fully stateless.
3. Contexts are per-operation and should not be stored.
4. 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).

Figure it out, especially point number 1. Update, expand, etc. TODO https://github.com/FerretDB/FerretDB/issues/3069

Index

• 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
• type CreateCollectionParams
• type Database
  • func DatabaseContract(db Database) Database
• type DatabaseInfo
• type DeleteParams
• type DeleteResult
• type DropCollectionParams
• type DropDatabaseParams
• 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 InsertParams
• type InsertResult
• type ListCollectionsParams
• type ListCollectionsResult
• type ListDatabasesParams
• type ListDatabasesResult
• type QueryParams
• type QueryResult
• type UpdateParams
• type UpdateResult

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()
	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 is expected to be stateful and wrap database connection(s). Handler can create one Backend or multiple Backends with different authentication credentials.

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)
	Insert(context.Context, *InsertParams) (*InsertResult, error)
	Update(context.Context, *UpdateParams) (*UpdateResult, error)
	Delete(context.Context, *DeleteParams) (*DeleteResult, error)
}

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

Collection object is expected to 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
}

CollectionInfo represents information about a single collection.

type CreateCollectionParams

type CreateCollectionParams struct {
	Name string
}

CreateCollectionParams represents the parameters of Database.CreateCollection method.

type Database

type Database interface {
	// TODO remove?
	Close()

	Collection(string) (Collection, error)
	ListCollections(context.Context, *ListCollectionsParams) (*ListCollectionsResult, error)
	CreateCollection(context.Context, *CreateCollectionParams) error
	DropCollection(context.Context, *DropCollectionParams) error
}

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

Database object is expected to be mostly 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 (but it should Close() them). Creating a Database object does not imply the creating of the database itself.

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 DeleteParams

type DeleteParams struct {
	// TODO https://github.com/FerretDB/FerretDB/issues/3085
	IDs []any
}

DeleteParams represents the parameters of Collection.Delete method.

type DeleteResult

type DeleteResult struct {
	Deleted int64
}

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

Error codes.

func (ErrorCode) String

func (i ErrorCode) String() string

type InsertParams

type InsertParams struct {
	// TODO https://github.com/FerretDB/FerretDB/issues/2750
	// that should be types.DocumentIterator
	Iter iterator.Interface[int, any]
}

InsertParams represents the parameters of Collection.Insert method.

type InsertResult

type InsertResult struct {
	Inserted int64
}

InsertResult represents the results of Collection.Insert 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 QueryParams

type QueryParams struct {
}

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 UpdateParams

type UpdateParams struct {
	// that should be types.DocumentIterator
	// TODO https://github.com/FerretDB/FerretDB/issues/3079
	Docs *types.Array
}

UpdateParams represents the parameters of Collection.Update method.

type UpdateResult

type UpdateResult struct {
	Updated int64
}

UpdateResult represents the results of Collection.Update method.