mongo

package
Version: v0.0.0-...-1d4245d Latest Latest
Warning

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

Go to latest
Published: Jun 27, 2022 License: AGPL-3.0 Imports: 42 Imported by: 213

Documentation

Index

Constants

View Source
const (
	// JujuDbSnap is the snap of MongoDB that Juju uses.
	JujuDbSnap = "juju-db"

	// JujuDbSnapMongodPath is the path that the juju-db snap
	// makes mongod available at
	JujuDbSnapMongodPath = "/snap/bin/juju-db.mongod"

	// MMAPV1 is the default storage engine in mongo db up to 3.x
	MMAPV1 StorageEngine = "mmapv1"

	// WiredTiger is a storage type introduced in 3
	WiredTiger StorageEngine = "wiredTiger"

	// Upgrading is a special case where mongo is being upgraded.
	Upgrading StorageEngine = "Upgrading"

	// SnapTrack is the track to get the juju-db snap from
	SnapTrack = "4.0"

	// SnapRisk is which juju-db snap to use i.e. stable or edge.
	SnapRisk = "stable"
)
View Source
const (
	// ServiceName is the name of the service that Juju's mongod instance
	// will be named.
	ServiceName = "juju-db"

	// SharedSecretFile is the name of the Mongo shared secret file
	// located within the Juju data directory.
	SharedSecretFile = "shared-secret"

	// ReplicaSetName is the name of the replica set that juju uses for its
	// controllers.
	ReplicaSetName = "juju"

	// LowCacheSize expressed in GB sets the max value Mongo WiredTiger cache can
	// reach.
	LowCacheSize = 1

	// Mongo34LowCacheSize changed to being a float, and allows you to specify down to 256MB
	Mongo34LowCacheSize = 0.25

	// FileNameDBSSLKey is the file name of db ssl key file name.
	FileNameDBSSLKey = "server.pem"
)
View Source
const AdminUser = "admin"

AdminUser is the name of the user that is initially created in mongo.

View Source
const SocketTimeout = time.Minute

SocketTimeout should be long enough that even a slow mongo server will respond in that length of time, and must also be long enough to allow for completion of heavyweight queries.

Note: 1 minute is mgo's default socket timeout value.

Also note: We have observed mongodb occasionally getting "stuck" for over 30s in the field.

Variables

View Source
var (

	// JujuMongod24Path holds the default path to the legacy Juju
	// mongod.
	JujuMongod24Path = "/usr/lib/juju/bin/mongod"

	// JujuMongod32Path holds the default path to juju-mongodb3.2
	JujuMongod32Path = "/usr/lib/juju/mongo3.2/bin/mongod"

	// MongodSystemPath is actually just the system path
	MongodSystemPath = "/usr/bin/mongod"
)
View Source
var (
	// Mongo24 represents juju-mongodb 2.4.x
	Mongo24 = Version{Major: 2,
		Minor:         4,
		Patch:         "",
		StorageEngine: MMAPV1,
	}
	// Mongo26 represents juju-mongodb26 2.6.x
	Mongo26 = Version{Major: 2,
		Minor:         6,
		Patch:         "",
		StorageEngine: MMAPV1,
	}
	// Mongo32wt represents juju-mongodb3 3.2.x with wiredTiger storage.
	Mongo32wt = Version{Major: 3,
		Minor:         2,
		Patch:         "",
		StorageEngine: WiredTiger,
	}
	// Mongo36wt represents 'mongodb-server-core' at version 3.6.x with WiredTiger
	Mongo36wt = Version{Major: 3,
		Minor:         6,
		Patch:         "",
		StorageEngine: WiredTiger,
	}
	// Mongo4xwt represents 'mongodb' at version 4.x with WiredTiger
	Mongo4xwt = Version{Major: 4,
		Minor:         0,
		Patch:         "",
		StorageEngine: WiredTiger,
	}
	// MongoUpgrade represents a special case where an upgrade is in
	// progress.
	MongoUpgrade = Version{Major: 0,
		Minor:         0,
		Patch:         "Upgrading",
		StorageEngine: Upgrading,
	}
)
View Source
var CurrentReplicasetConfig = func(session *mgo.Session) (*replicaset.Config, error) {
	return replicaset.CurrentConfig(session)
}

CurrentReplicasetConfig is overridden in tests.

View Source
var IsMaster = isMaster

IsMaster returns a boolean that represents whether the given machine's peer address is the primary mongo host for the replicaset

View Source
var IsServiceInstalled = isServiceInstalled

IsServiceInstalled returns whether the MongoDB init service configuration is present.

Functions

func DbDir

func DbDir(dataDir string) string

DbDir returns the dir where mongo storage is.

func DialInfo

func DialInfo(info Info, opts DialOpts) (*mgo.DialInfo, error)

DialInfo returns information on how to dial the state's mongo server with the given info and dial options.

func DialWithInfo

func DialWithInfo(info MongoInfo, opts DialOpts) (*mgo.Session, error)

DialWithInfo establishes a new session to the cluster identified by info, with the specified options. If either Tag or Password are specified, then a Login call on the admin database will be made.

func EnsureServiceInstalled

func EnsureServiceInstalled(dataDir string, statePort int, oplogSizeMB int, setNUMAControlPolicy bool, version Version, auth bool, memProfile MemoryProfile) error

EnsureServiceInstalled is a convenience method to [re]create the mongo service. It assumes that the necessary packages are already installed and that the file system includes secrets at dataDir.

func GenerateSSLKey

func GenerateSSLKey(cert, privateKey string) string

GenerateSSLKey combines cert and private key to generate the ssl key - server.pem.

func GenerateSharedSecret

func GenerateSharedSecret() (string, error)

GenerateSharedSecret generates a pseudo-random shared secret (keyfile) for use with Mongo replica sets.

func GetOplog

func GetOplog(session *mgo.Session) *mgo.Collection

GetOplog returns the the oplog collection in the local database.

func JujuMongodPath

func JujuMongodPath(v Version) string

JujuMongodPath returns the path for the mongod binary with the specified version.

func Login

func Login(session *mgo.Session, user, password string) error

Login logs in to the mongodb admin database.

func MaybeUnauthorizedf

func MaybeUnauthorizedf(err error, message string, args ...interface{}) error

MaybeUnauthorizedf checks if the cause of the given error is a Mongo authorization error, and if so, wraps the error with errors.Unauthorizedf.

func NewMongoTimestamp

func NewMongoTimestamp(t time.Time) bson.MongoTimestamp

NewMongoTimestamp returns a bson.MongoTimestamp repesentation for the time.Time given. Note that these timestamps are not the same the usual MongoDB time fields. These are an internal format used only in a few places such as the replication oplog.

See: http://docs.mongodb.org/manual/reference/bson-types/#timestamps

func NewOplogSession

func NewOplogSession(collection *mgo.Collection, query bson.D) *oplogSession

NewOplogSession defines a new OplogSession.

Arguments: - "collection" is the collection to use for the oplog. Typically this

would be the result of GetOpLog.

- "query" can be used to limit the returned oplog entries. A

typical filter would limit based on ns ("<database>.<collection>")
and o (object).

The returned session should be `Close`d when it's no longer needed.

func Path

func Path(version Version) (string, error)

Path returns the executable path to be used to run mongod on this machine. If the juju-bundled version of mongo exists, it will return that path, otherwise it will return the command to run mongod from the path.

func ReStartService

func ReStartService() error

ReStartService will stop and then start mongodb service.

func RemoveService

func RemoveService() error

RemoveService removes the mongoDB init service from this machine.

func SelectPeerAddress

func SelectPeerAddress(addrs network.ProviderAddresses) string

SelectPeerAddress returns the address to use as the mongo replica set peer address by selecting it from the given addresses. If no addresses are available an empty string is returned.

func SetAdminMongoPassword

func SetAdminMongoPassword(session *mgo.Session, user, password string) error

SetAdminMongoPassword sets the administrative password to access a mongo database. If the password is non-empty, all subsequent attempts to access the database must be authorized; otherwise no authorization is required.

func StartService

func StartService() error

StartService will start mongodb service.

func StopService

func StopService() error

StopService will stop mongodb service.

func UpdateSSLKey

func UpdateSSLKey(dataDir, cert, privateKey string) error

UpdateSSLKey writes a new SSL key used by mongo to validate connections from Juju controller(s)

Types

type Collection

type Collection interface {

	// Name returns the name of the collection.
	Name() string

	// Count, Find, and FindId methods act as documented for *mgo.Collection.
	Count() (int, error)
	Find(query interface{}) Query
	FindId(id interface{}) Query
	Pipe(pipeline interface{}) *mgo.Pipe

	// Writeable gives access to methods that enable direct DB access. It
	// should be used with judicious care, and for only the best of reasons.
	Writeable() WriteCollection
}

Collection imperfectly insulates clients from the capacity to write to MongoDB. Query results can still be used to write; and the Writeable method exposes the underlying *mgo.Collection when absolutely required; but the general expectation in juju is that writes will occur only via mgo/txn, and any layer-skipping is done only in exceptional and well- supported circumstances.

func CollectionFromName

func CollectionFromName(db *mgo.Database, coll string) (Collection, func())

CollectionFromName returns a named collection on the specified database, initialised with a new session. Also returned is a close function which must be called when the collection is no longer required.

func WrapCollection

func WrapCollection(coll *mgo.Collection) Collection

WrapCollection returns a Collection that wraps the supplied *mgo.Collection.

type ConfigArgs

type ConfigArgs struct {
	DataDir    string
	DBDir      string
	MongoPath  string
	ReplicaSet string
	Version    Version

	// connection params
	BindIP      string
	BindToAllIP bool
	Port        int
	OplogSizeMB int

	// auth
	AuthKeyFile    string
	PEMKeyFile     string
	PEMKeyPassword string

	// network params
	IPv6             bool
	SSLOnNormalPorts bool
	SSLMode          string

	// logging
	Syslog    bool
	LogAppend bool
	LogPath   string

	// db kernel
	WantNUMACtl           bool
	MemoryProfile         MemoryProfile
	Journal               bool
	NoPreAlloc            bool
	SmallFiles            bool
	WiredTigerCacheSizeGB float32

	// misc
	Quiet bool
}

ConfigArgs holds the attributes of a service configuration for mongo.

type DialOpts

type DialOpts struct {
	// Timeout is the amount of time to wait contacting
	// a controller.
	Timeout time.Duration

	// SocketTimeout is the amount of time to wait for a
	// non-responding socket to the database before it is forcefully
	// closed. If this is zero, the value of the SocketTimeout const
	// will be used.
	SocketTimeout time.Duration

	// Direct informs whether to establish connections only with the
	// specified seed servers, or to obtain information for the whole
	// cluster and establish connections with further servers too.
	Direct bool

	// PostDial, if non-nil, is called by DialWithInfo with the
	// mgo.Session after a successful dial but before DialWithInfo
	// returns to its caller.
	PostDial func(*mgo.Session) error

	// PostDialServer, if non-nil, is called by DialWithInfo after
	// dialing a MongoDB server connection, successfully or not.
	// The address dialed and amount of time taken are included,
	// as well as the error if any.
	PostDialServer func(addr string, _ time.Duration, _ error)

	// PoolLimit defines the per-server socket pool limit
	PoolLimit int
}

DialOpts holds configuration parameters that control the Dialing behavior when connecting to a controller.

func DefaultDialOpts

func DefaultDialOpts() DialOpts

DefaultDialOpts returns a DialOpts representing the default parameters for contacting a controller.

NOTE(axw) these options are inappropriate for tests in CI, as CI tends to run on machines with slow I/O (or thrashed I/O with limited IOPs). For tests, use mongotest.DialOpts().

type EnsureServerParams

type EnsureServerParams struct {
	// APIPort is the port to connect to the api server.
	APIPort int

	// StatePort is the port to connect to the mongo server.
	StatePort int

	// Cert is the certificate.
	Cert string

	// PrivateKey is the certificate's private key.
	PrivateKey string

	// CAPrivateKey is the CA certificate's private key.
	CAPrivateKey string

	// SharedSecret is a secret shared between mongo servers.
	SharedSecret string

	// SystemIdentity is the identity of the system.
	SystemIdentity string

	// DataDir is the machine agent data directory.
	DataDir string

	// LogDir is where mongo logs go.
	LogDir string

	// Namespace is the machine agent's namespace, which is used to
	// generate a unique service name for Mongo.
	Namespace string

	// OplogSize is the size of the Mongo oplog.
	// If this is zero, then EnsureServer will
	// calculate a default size according to the
	// algorithm defined in Mongo.
	OplogSize int

	// SetNUMAControlPolicy preference - whether the user
	// wants to set the numa control policy when starting mongo.
	SetNUMAControlPolicy bool

	// MemoryProfile determines which value is going to be used by
	// the cache and future memory tweaks.
	MemoryProfile MemoryProfile

	// The channel for installing the mongo snap in focal and later.
	JujuDBSnapChannel string
}

EnsureServerParams is a parameter struct for EnsureServer.

type Info

type Info struct {
	// Addrs gives the addresses of the MongoDB servers for the state.
	// Each address should be in the form address:port.
	Addrs []string

	// CACert holds the CA certificate that will be used
	// to validate the controller's certificate, in PEM format.
	CACert string

	// DisableTLS controls whether the connection to MongoDB servers
	// is made using TLS (the default), or not.
	DisableTLS bool
}

Info encapsulates information about cluster of mongo servers and can be used to make a connection to that cluster.

type Iterator

type Iterator interface {
	Next(interface{}) bool
	Timeout() bool
	Close() error
}

Iterator defines the parts of the mgo.Iter that we use - this interface allows us to switch out the querying for testing.

type MemoryProfile

type MemoryProfile string

MemoryProfile represents a type of meory configuration for Mongo.

const (
	// MemoryProfileLow will use as little memory as possible in mongo.
	MemoryProfileLow MemoryProfile = "low"
	// MemoryProfileDefault will use mongo config ootb.
	MemoryProfileDefault MemoryProfile = "default"
)

func NewMemoryProfile

func NewMemoryProfile(m string) (MemoryProfile, error)

NewMemoryProfile returns a Memory Profile from the passed value.

func (MemoryProfile) String

func (m MemoryProfile) String() string

String returns a string representation of this profile value.

func (MemoryProfile) Validate

func (m MemoryProfile) Validate() error

type MongoInfo

type MongoInfo struct {
	// mongo.Info contains the addresses and cert of the mongo cluster.
	Info

	// Tag holds the name of the entity that is connecting.
	// It should be nil when connecting as an administrator.
	Tag names.Tag

	// Password holds the password for the connecting entity.
	Password string
}

MongoInfo encapsulates information about cluster of servers holding juju state and can be used to make a connection to that cluster.

type MongodFinder

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

MongodFinder searches expected paths to find a version of Mongo and determine what version it is.

func NewMongodFinder

func NewMongodFinder() *MongodFinder

NewMongodFinder returns a type that will help search for mongod, using normal OS tools.

func (*MongodFinder) FindBest

func (m *MongodFinder) FindBest() (string, Version, error)

FindBest tries to find the mongo version that best fits what we want to use.

type OSSearchTools

type OSSearchTools struct{}

func (OSSearchTools) Exists

func (OSSearchTools) Exists(name string) bool

func (OSSearchTools) GetCommandOutput

func (OSSearchTools) GetCommandOutput(name string, arg ...string) (string, error)

type OplogDoc

type OplogDoc struct {
	Timestamp    bson.MongoTimestamp `bson:"ts"`
	OperationId  int64               `bson:"h"`
	MongoVersion int                 `bson:"v"`
	Operation    string              `bson:"op"` // "i" - insert, "u" - update, "d" - delete
	Namespace    string              `bson:"ns"`
	Object       *bson.Raw           `bson:"o"`
	UpdateObject *bson.Raw           `bson:"o2"`
}

OplogDoc represents a document in the oplog.rs collection. See: http://www.kchodorow.com/blog/2010/10/12/replication-internals/

The Object and UpdateObject fields are returned raw to allow unmarshalling into arbitrary types. Use the UnmarshalObject and UnmarshalUpdate methods to unmarshall these fields.

func (*OplogDoc) UnmarshalObject

func (d *OplogDoc) UnmarshalObject(out interface{}) error

UnmarshalObject unmarshals the Object field into out. The out argument should be a pointer or a suitable map.

func (*OplogDoc) UnmarshalUpdate

func (d *OplogDoc) UnmarshalUpdate(out interface{}) error

UnmarshalUpdate unmarshals the UpdateObject field into out. The out argument should be a pointer or a suitable map.

type OplogSession

type OplogSession interface {
	NewIter(bson.MongoTimestamp, []int64) Iterator
	Close()
}

OplogSession represents a connection to the oplog store, used to create an iterator to get oplog documents (and recreate it if it gets killed or times out).

type OplogTailer

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

OplogTailer tails MongoDB's replication oplog.

func NewOplogTailer

func NewOplogTailer(
	session OplogSession,
	initialTs time.Time,
) *OplogTailer

NewOplogTailer returns a new OplogTailer.

Arguments: - "session" determines the collection and filtering on records that

should be returned.

- "initialTs" sets the operation timestamp to start returning

results from. This can be used to avoid an expensive initial search
through the oplog when the tailer first starts.

Remember to call Stop on the returned OplogTailer when it is no longer needed.

func (*OplogTailer) Dying

func (t *OplogTailer) Dying() <-chan struct{}

Dying returns a channel that will be closed with the OplogTailer is shutting down.

func (*OplogTailer) Err

func (t *OplogTailer) Err() error

Err returns the error that caused the OplogTailer to stop. If it finished normally or hasn't stopped then nil will be returned.

func (*OplogTailer) Out

func (t *OplogTailer) Out() <-chan *OplogDoc

Out returns a channel that reports the oplog entries matching the query passed to NewOplogTailer as they appear.

func (*OplogTailer) Stop

func (t *OplogTailer) Stop() error

Stop shuts down the OplogTailer. It will block until shutdown is complete.

type Query

type Query interface {
	All(result interface{}) error
	Apply(change mgo.Change, result interface{}) (info *mgo.ChangeInfo, err error)
	Batch(n int) Query
	Comment(comment string) Query
	Count() (n int, err error)
	Distinct(key string, result interface{}) error
	Explain(result interface{}) error
	For(result interface{}, f func() error) error
	Hint(indexKey ...string) Query
	Iter() Iterator
	Limit(n int) Query
	LogReplay() Query
	MapReduce(job *mgo.MapReduce, result interface{}) (info *mgo.MapReduceInfo, err error)
	One(result interface{}) (err error)
	Prefetch(p float64) Query
	Select(selector interface{}) Query
	SetMaxScan(n int) Query
	SetMaxTime(d time.Duration) Query
	Skip(n int) Query
	Snapshot() Query
	Sort(fields ...string) Query
	Tail(timeout time.Duration) *mgo.Iter
}

Query allows access to a portion of a MongoDB collection.

type SearchTools

type SearchTools interface {
	// GetCommandOutput execs the given command, and returns the CombinedOutput, or any error that occurred.
	GetCommandOutput(name string, arg ...string) (string, error)

	// Exists just returns if a given path is available (eg os.Stat() has a value)
	Exists(string) bool
}

SearchTools represents the OS functionality we need to find the correct MongoDB executable. The mock for this (used in testing) is automatically generated by 'go generate' from the following line

type StorageEngine

type StorageEngine string

StorageEngine represents the storage used by mongo.

type Version

type Version struct {
	Major         int
	Minor         int
	Point         int
	Patch         string // supports variants like 1-alpha
	StorageEngine StorageEngine
}

Version represents the major.minor version of the running mongo.

func EnsureServer

func EnsureServer(args EnsureServerParams) (Version, error)

EnsureServer ensures that the MongoDB server is installed, configured, and ready to run.

This method will remove old versions of the mongo init service as necessary before installing the new version.

func NewVersion

func NewVersion(v string) (Version, error)

NewVersion returns a mongo Version parsing the passed version string or error if not possible. A valid version string is of the form: 1.2.patch/storage major and minor are positive integers, patch is a string containing any ascii character except / and storage is one of the above defined StorageEngine. Only major is mandatory. An alternative valid string is 0.0/Upgrading which represents that mongo is being upgraded.

func ParseMongoVersion

func ParseMongoVersion(versionInfo string) (Version, error)

ParseMongoVersion parses the output from "mongod --version" and returns a Version struct

func (Version) NewerThan

func (v Version) NewerThan(ver Version) int

NewerThan will return 1 if the passed version is older than v, 0 if they are equal (or ver is a special case such as Upgrading and -1 if ver is newer.

func (Version) String

func (v Version) String() string

String serializes the version into a string.

type WithAddresses

type WithAddresses interface {
	Addresses() network.SpaceAddresses
}

WithAddresses represents an entity that has a set of addresses. e.g. a state Machine object

type WriteCollection

type WriteCollection interface {
	Collection

	// Underlying returns the underlying *mgo.Collection.
	Underlying() *mgo.Collection

	// All other methods act as documented for *mgo.Collection.
	Insert(docs ...interface{}) error
	Upsert(selector interface{}, update interface{}) (info *mgo.ChangeInfo, err error)
	UpsertId(id interface{}, update interface{}) (info *mgo.ChangeInfo, err error)
	Update(selector interface{}, update interface{}) error
	UpdateId(id interface{}, update interface{}) error
	Remove(sel interface{}) error
	RemoveId(id interface{}) error
	RemoveAll(sel interface{}) (*mgo.ChangeInfo, error)
}

WriteCollection allows read/write access to a MongoDB collection.

Directories

Path Synopsis
Package mongometrics contains MongodB-related Prometheus metric collectors.
Package mongometrics contains MongodB-related Prometheus metric collectors.

Jump to

Keyboard shortcuts

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