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 

type Collection interface {
	Query(context.Context, *QueryParams) (*QueryResult, error)
	Explain(context.Context, *ExplainParams) (*ExplainResult, error)
	InsertAll(context.Context, *InsertAllParams) (*InsertAllResult, error)
	UpdateAll(context.Context, *UpdateAllParams) (*UpdateAllResult, error)
	DeleteAll(context.Context, *DeleteAllParams) (*DeleteAllResult, 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
	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 

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
}

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.