# Poco::MongoDB

# class Database

Library: MongoDB
Package: MongoDB
Header: Poco/MongoDB/Database.h

## Description

Database is a helper class for creating requests. MongoDB works with collection names and uses the part before the first dot as the name of the database.

## Member Summary

Member Functions: authSCRAM, authSCRAM256, authenticate, count, createIndex, createOpMsgCursor, createOpMsgMessage, name, queryBuildInfo, queryServerHello

## Types Aliases

### FieldIndex

using FieldIndex = std::tuple < std::string, bool >;

name of the field to index, ascending order (true), descending order (false)

### IndexedFields

using IndexedFields = std::vector < FieldIndex >;

Vector of fields to create index on

## Enumerations

### IndexOptions

INDEX_UNIQUE = 1 << 0

< For new indexes with conditional-inclusion semantics, prefer < partialFilterExpression (see createIndex with extraOptions) < over INDEX_SPARSE.

INDEX_SPARSE = 1 << 1

INDEX_BACKGROUND = 1 << 2

< Hybrid online index builds since 4.2; no longer forwarded to the server.

INDEX_HIDDEN = 1 << 3

< Hide the index from the query planner (since MongoDB 4.4).

### WireVersion

Wire version as reported by the command hello. See details in MongoDB github, repository specifications. @see queryServerHello

VER_26 = 1

VER_26_2 = 2

VER_30 = 3

VER_32 = 4

VER_34 = 5

VER_36 = 6

< First wire version that supports OP_MSG

VER_40 = 7

VER_42 = 8

VER_44 = 9

VER_50 = 13

VER_51 = 14

< First wire version that supports *only* OP_MSG

VER_52 = 15

VER_53 = 16

VER_60 = 17

VER_61 = 18

VER_62 = 19

VER_70 = 21

VER_71 = 22

VER_72 = 23

VER_73 = 24

VER_80 = 25

## Constructors

### Database

explicit Database(
const std::string & name
);

Creates a Database for the database with the given name.

## Destructor

### ~Database

virtual ~Database();

Destroys the Database.

## Member Functions

### authenticate

bool authenticate(
Connection & connection,
const std::string & username,
const std::string & password,
const std::string & method = AUTH_SCRAM_SHA256
);

Authenticates against the database using the given connection, username and password, and authentication method:

- "SCRAM-SHA-256" (MongoDB 4.0+)
- "SCRAM-SHA-1" (MongoDB 3.0+)

MONGODB-CR is not supported (requires the legacy wire protocol).

SCRAM-SHA-256 accepts ASCII passwords only; SASLprep (RFC 4013) is not implemented. Non-ASCII throws Poco::NotImplementedException.

Returns true on success, false on invalid credentials. Throws Poco::ProtocolException on other failures.

### count

[[nodiscard]]
Int64 count(
Connection & connection,
const std::string & collectionName
) const;

Counts documents in the given collection using the aggregation framework ([{$count: "n"}]) over OP_MSG. Aggregation-based counting is preferred over the legacy "count" command because it is part of the Stable API v1 (since MongoDB 5.0), is accurate on sharded clusters (the legacy command can over-report due to orphaned documents), and is permitted in multi-document transactions.

If the command fails, -1 is returned.

### createIndex

Document::Ptr createIndex(
Connection & connection,
const std::string & collection,
const IndexedFields & indexedFields,
const std::string & indexName,
unsigned long options = 0,
int expirationSeconds = 0,
int version = 0
);

Creates an index. The document returned is the response body. For more info look at the createIndex information on the MongoDB website. (new wire protocol)

Leave version at 0 to use the server default (v=2 since MongoDB 3.4). Setting v=1 is only for compatibility with pre-3.4 servers and is incompatible with text, wildcard, and several other modern index types.

### createIndex

Document::Ptr createIndex(
Connection & connection,
const std::string & collection,
const IndexedFields & indexedFields,
const std::string & indexName,
Document::Ptr extraOptions,
unsigned long options = 0,
int expirationSeconds = 0,
int version = 0
);

Creates an index, allowing arbitrary additional fields in the per-index spec via extraOptions. Every element of extraOptions is added to the index spec document on top of the fields derived from indexedFields, indexName, options, expirationSeconds and version. Typical keys to pass in extraOptions include:

- "partialFilterExpression" (Document): partial indexes, MongoDB 3.2+. Preferred over INDEX_SPARSE for new code.
- "collation" (Document): per-index collation, MongoDB 3.4+.
- "wildcardProjection" (Document): wildcard / compound-wildcard indexes (the wildcard field itself is specified as "$**" or "path.$**" in indexedFields).
- "weights", "default_language", "language_override" (text indexes).
- "2dsphereIndexVersion", "bits", "min", "max" (geo indexes).

The document returned is the createIndexes response body.

### createOpMsgCursor

[[nodiscard]]
SharedPtr < OpMsgCursor > createOpMsgCursor(
const std::string & collectionName
) const;

Creates OpMsgCursor for the given collection.

### createOpMsgMessage

[[nodiscard]]
SharedPtr < OpMsgMessage > createOpMsgMessage(
const std::string & collectionName
) const;

Creates OpMsgMessage for the given collection.

### createOpMsgMessage

[[nodiscard]]
SharedPtr < OpMsgMessage > createOpMsgMessage() const;

Creates OpMsgMessage for database commands that do not require collection as an argument.

### name

[[nodiscard]]
const std::string & name() const;

Database name

### queryBuildInfo

[[nodiscard]]
Document::Ptr queryBuildInfo(
Connection & connection
) const;

Queries server build info using OP_MSG protocol.

### queryServerHello

[[nodiscard]]
Document::Ptr queryServerHello(
Connection & connection
) const;

Queries hello response from server using OP_MSG protocol.

### authSCRAM

bool authSCRAM(
Connection & connection,
const std::string & username,
const std::string & password
);

Performs SCRAM-SHA-1 authentication.

### authSCRAM256

bool authSCRAM256(
Connection & connection,
const std::string & username,
const std::string & password
);

Performs SCRAM-SHA-256 authentication. ASCII passwords only.

## Variables

### AUTH_SCRAM_SHA1

static const std::string AUTH_SCRAM_SHA1;

SCRAM-SHA-1 authentication mechanism (MongoDB 3.0+).

### AUTH_SCRAM_SHA256

static const std::string AUTH_SCRAM_SHA256;

SCRAM-SHA-256 authentication mechanism (MongoDB 4.0+).