# Poco::MongoDB

# class Connection

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

## Description

Represents a connection to a MongoDB server using the MongoDB wire protocol.

See https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/ for more information on the wire protocol.

THREAD SAFETY: This class is NOT thread-safe. A single Connection instance must not be used concurrently from multiple threads without external synchronization. Concurrent calls to sendRequest() will result in interleaved data on the socket and corrupted responses.

For multi-threaded applications, use one of these patterns: - Each thread has its own Connection instance - Use ObjectPool<Connection> with PooledConnection for connection pooling - Protect shared Connection with external mutex

## Member Summary

Member Functions: address, connect, disconnect, readResponse, sendRequest

## Nested Classes

### class SocketFactory

## Types Aliases

### Ptr

using Ptr = Poco::SharedPtr < Connection >;

## Constructors

### Connection

Connection();

Creates an unconnected Connection.

Use this when you want to connect later on.

### Connection

Connection(
const std::string & hostAndPort
);

Creates a Connection connected to the given MongoDB instance at host:port.

The host and port must be separated with a colon.

### Connection

Connection(
const Poco::Net::SocketAddress & addrs
);

Creates a Connection connected to the given MongoDB instance at the given address.

### Connection

Connection(
const Poco::Net::StreamSocket & socket
);

Creates a Connection connected to the given MongoDB instance using the given socket, which must already be connected.

### Connection

Connection(
const std::string & uri,
SocketFactory & socketFactory
);

Creates a Connection connected to the given MongoDB instance at the given URI.

See the corresponding connect() method for more information.

### Connection

Connection(
const std::string & host,
int port
);

Creates a Connection connected to the given MongoDB instance at host and port.

## Destructor

### ~Connection

virtual ~Connection();

Destroys the Connection.

## Member Functions

### address

[[nodiscard]]
Poco::Net::SocketAddress address() const;

Returns the address of the MongoDB server.

### connect

void connect(
const std::string & hostAndPort
);

Connects to the given MongoDB server.

The host and port must be separated with a colon.

### connect

void connect(
const std::string & uri,
SocketFactory & socketFactory
);

Connects to the given MongoDB instance at the given URI.

The URI must be in standard MongoDB connection string URI format:

    mongodb://<user>:<password>@hostname.com:<port>/database-name?options

The following options are supported:

- tls (or ssl, historical alias): If true, a custom SocketFactory subclass creating a SecureStreamSocket must be supplied. "tls" is the canonical option name since MongoDB 4.2; "ssl" remains accepted as a synonym.
- connectTimeoutMS: Socket connection timeout in milliseconds.
- socketTimeoutMS: Socket send/receive timeout in milliseconds.
- authMechanism: "SCRAM-SHA-256" (default) or "SCRAM-SHA-1".

Unknown options are silently ignored.

Will also attempt to authenticate using the specified credentials, using Database::authenticate().

Throws a Poco::NoPermissionException if authentication fails.

### connect

void connect(
const std::string & host,
int port
);

Connects to the given MongoDB server.

### connect

void connect(
const Poco::Net::SocketAddress & addrs
);

Connects to the given MongoDB server.

### connect

void connect(
const Poco::Net::SocketAddress & addrs,
const Poco::Timespan & connectTimeout,
const Poco::Timespan & socketTimeout = 0
);

Connects to the given MongoDB server with the specified connect timeout. If connectTimeout is non-zero, the connection attempt will be aborted after the specified time. If socketTimeout is non-zero, the send and receive timeouts on the socket will be set after a successful connection.

### connect

void connect(
const Poco::Net::StreamSocket & socket
);

Connects using an already connected socket.

### disconnect

void disconnect();

Disconnects from the MongoDB server.

### readResponse

void readResponse(
OpMsgMessage & response
);

Reads additional response data when previous message's flag moreToCome indicates that server will send more data. NOTE: See comments in OpMsgCursor code.

### sendRequest

void sendRequest(
OpMsgMessage & request,
OpMsgMessage & response
);

Sends a request to the MongoDB server and receives the response using OP_MSG wire protocol.

### sendRequest

void sendRequest(
OpMsgMessage & request
);

Sends an unacknowledged request to the MongoDB server using OP_MSG wire protocol. No response is sent by the server.

### connect

void connect();