mongo

Documentation

Overview

Package mongo provides convenient API to mongodb. It uses mongo official driver undercover.

Typical simplified usage:

client := mongo.MustNewClient(mongo.WithAddress("127.0.0.1:27017"))
defer client.Close()

if err := client.Ping(); err != nil {
    ...
}

session := client.Session(ctx, dbName, collectionName)
count, err := session.Find(mongo.Data{}, &entities)
if err != nil {
    ...
}

Index

• Constants
• type Client
  • func MustNewClient(opts ...Option) *Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (client *Client) Address() string
  • func (client *Client) Close() error
  • func (client *Client) ConnectTimeout() time.Duration
  • func (client *Client) Ping() error
  • func (client *Client) Session(ctx context.Context, databaseName string, collectionName string) *Session
  • func (client *Client) SocketTimeout() time.Duration
• type Config
• type ConfigService
• type Data
• type Option
  • func WithAddress(address string) Option
  • func WithConfig(service ConfigService, key string) Option
  • func WithConnectTimeout(idleTimeout int) Option
  • func WithSocketTimeout(socketTimeout int) Option
• type Session
  • func (session *Session) Collection() string
  • func (session *Session) Context() context.Context
  • func (session *Session) Count(filter Data) (int64, error)
  • func (session *Session) CountAll() (int64, error)
  • func (session *Session) Database() string
  • func (session *Session) DeleteMany(filter Data) (int64, error)
  • func (session *Session) DeleteOne(filter Data) (int64, error)
  • func (session *Session) Drop() error
  • func (session *Session) Find(filter Data, entities interface{}, opts ...*options.FindOptions) (int64, error)
  • func (session *Session) FindOne(filter Data, entity interface{}, opts ...*options.FindOneOptions) (int64, error)
  • func (session *Session) InsertMany(entities []interface{}) ([]interface{}, error)
  • func (session *Session) InsertOne(entity interface{}) (interface{}, error)
  • func (session *Session) UpdateMany(filter Data, entity interface{}) (*mongo.UpdateResult, error)
  • func (session *Session) UpdateOne(filter Data, entity interface{}) (*mongo.UpdateResult, error)
  • func (session *Session) UpsertMany(filter Data, entity interface{}) (*mongo.UpdateResult, error)
  • func (session *Session) UpsertOne(filter Data, entity interface{}) (*mongo.UpdateResult, error)
  • func (session *Session) WithCollection(name string) *Session
  • func (session *Session) WithContext(ctx context.Context) *Session
  • func (session *Session) WithDatabase(databaseName string, collectionName string) *Session

Constants

const (
	// DefAddress is the default mongo server address.
	DefAddress = "127.0.0.1:27017"
	// DefConnectTimeout is the default mongo client connect timeout in seconds.
	DefConnectTimeout = 15
	// DefSocketTimeout is the default mongo client socket timeout in seconds.
	DefSocketTimeout = 30
)

Types

type Client

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

Client structure provides mongo client functionality. Don't create manually, use the functions down below instead.

func MustNewClient

func MustNewClient(opts ...Option) *Client

MustNewClient function creates new mongo client with provided options and panics on any error.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient function creates new mongo client with provided options.

func (*Client) Address

func (client *Client) Address() string

Address method retrieves mongo server address.

func (*Client) Close

func (client *Client) Close() error

Close method releases all resources used by client. Don't use client object after that.

func (*Client) ConnectTimeout

func (client *Client) ConnectTimeout() time.Duration

ConnectTimeout method retrieves mongo client connect timeout.

func (*Client) Ping

func (client *Client) Ping() error

Ping method pings mongo server to check that connection is successfully established.

func (*Client) Session

func (client *Client) Session(ctx context.Context, databaseName string, collectionName string) *Session

Session method creates new session to perform useful commands on mongodb database and collection.

func (*Client) SocketTimeout

func (client *Client) SocketTimeout() time.Duration

SocketTimeout method retrieves mongo client socket timeout.

type Config

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

Config structure with client's configuration. Shouldn't be created manually.

type ConfigService

type ConfigService interface {
	GetByKey(string, interface{}) error
	IsNoSuchKeyError(error) bool
}

ConfigService interface used to obtain configuration from somewhere into some specific structure.

type Data

type Data bson.D

Data type is used to provide filters in various mongodb commands.

type Option

type Option func(*Config) error

Option function that is fed to NewClient and MustNewClient. Obtain them using 'With' functions down below.

func WithAddress

func WithAddress(address string) Option

WithAddress option applies provided mongo server address. Default: "127.0.0.1:27017".

func WithConfig

func WithConfig(service ConfigService, key string) Option

WithConfig option retrieves configuration from provided configuration service.

Example JSON configuration with all possible fields (if some are not present, defaults will be used):

{
    "address": "127.0.0.1:27017",
    "connectTimeout": 5,
    "socketTimeout": 10
}

func WithConnectTimeout

func WithConnectTimeout(idleTimeout int) Option

WithConnectTimeout option applies provided mongo client connect timeout in seconds. Default: 15.

func WithSocketTimeout

func WithSocketTimeout(socketTimeout int) Option

WithSocketTimeout option applies provided mongo client socket timeout in seconds. Default: 30.

type Session

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

Session structure provides access to operations with mongodb database and collection.

func (*Session) Collection

func (session *Session) Collection() string

Collection method retrieves session collection name.

func (*Session) Context

func (session *Session) Context() context.Context

Context method retrieves session context.

func (*Session) Count

func (session *Session) Count(filter Data) (int64, error)

Count method retrieves number of entities in collection satisfying filter.

func (*Session) CountAll

func (session *Session) CountAll() (int64, error)

CountAll method retrieves total number of entities in collection.

func (*Session) Database

func (session *Session) Database() string

Database method retrieves session database name.

func (*Session) DeleteMany

func (session *Session) DeleteMany(filter Data) (int64, error)

DeleteMany method deletes all entities from collection using filter. On success it returns number of deleted entities.

func (*Session) DeleteOne

func (session *Session) DeleteOne(filter Data) (int64, error)

DeleteOne method deletes entity from collection using filter. On success, it returns number of deleted entities (0 or 1).

func (*Session) Drop

func (session *Session) Drop() error

Drop method drops collection completely.

func (*Session) Find

func (session *Session) Find(filter Data, entities interface{}, opts ...*options.FindOptions) (int64, error)

Find method retrieves list of entities from collection using filter into entities parameter that must be a pointer to a slice of appropriate structures. On success, it returns number of retrieved entities.

func (*Session) FindOne

func (session *Session) FindOne(filter Data, entity interface{}, opts ...*options.FindOneOptions) (int64, error)

FindOne method retrieves one entity from collection using filter into entity parameter that must be a pointer to appropriate structure. On success, it returns number of retrieved entities.

func (*Session) InsertMany

func (session *Session) InsertMany(entities []interface{}) ([]interface{}, error)

InsertMany method inserts list of entities into collection. On success it returns ids of inserted entities.

func (*Session) InsertOne

func (session *Session) InsertOne(entity interface{}) (interface{}, error)

InsertOne method inserts entity into collection. On success it returns id of inserted entity.

func (*Session) UpdateMany

func (session *Session) UpdateMany(filter Data, entity interface{}) (*mongo.UpdateResult, error)

UpdateMany method updates list of entities in collection using filter. On success it returns structure with update result.

func (*Session) UpdateOne

func (session *Session) UpdateOne(filter Data, entity interface{}) (*mongo.UpdateResult, error)

UpdateOne method updates entity in collection using filter. On success it returns structure with update result.

func (*Session) UpsertMany

func (session *Session) UpsertMany(filter Data, entity interface{}) (*mongo.UpdateResult, error)

UpsertMany method updates list of entities in collection using filter. If nothing to update, new entity will be inserted. On success, it returns structure with update result.

func (*Session) UpsertOne

func (session *Session) UpsertOne(filter Data, entity interface{}) (*mongo.UpdateResult, error)

UpsertOne method updates entity in collection using filter. If nothing to update, new entity will be inserted. On success it returns structure with update result.

func (*Session) WithCollection

func (session *Session) WithCollection(name string) *Session

WithCollection method changes session collection.

func (*Session) WithContext

func (session *Session) WithContext(ctx context.Context) *Session

WithContext method changes session context.

func (*Session) WithDatabase

func (session *Session) WithDatabase(databaseName string, collectionName string) *Session

WithDatabase method changes session database and collection.