class Mongo::Client

Overview

The client which provides access to a MongoDB server, replica set, or sharded cluster.

It maintains management of underlying sockets and routing to individual nodes.

Included Modules

Defined in:

cryomongo/client.cr

Constant Summary

MAX_WIRE_VERSION = 8

The maximum wire protocol version supported by this driver.

MIN_WIRE_VERSION = 6

The mininum wire protocol version supported by this driver.

Constructors

Instance Method Summary

Constructor Detail

def self.new(connection_string : String = "mongodb://localhost:27017", options : Mongo::Options = Mongo::Options.new) #

Create a mongodb client instance from a mongodb URL.

require "cryomongo"

client = Mongo::Client.new "mongodb://127.0.0.1/?appname=client-example"

Instance Method Detail

def [](name : String) : Database #

Get a newly allocated Mongo::Databaseusing the default auth database string optionally provided as a part of the connection string uri.

see: https://docs.mongodb.com/manual/reference/connection-string/


def close #

Frees all the resources associated with a client.


def cluster_time : Session::ClusterTime | Nil #

The current highest seen cluster time for the deployment


def command(command, write_concern : WriteConcern | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, server_description : SDAM::ServerDescription | Nil = nil, session : Session::ClientSession | Nil = nil, operation_id : Int64 | Nil = nil, **args, &) #

Execute a command on the server.

# First argument is the `Mongo::Commands`.
client.command(Mongo::Commands::DropDatabase, database: "database_name")

def command(command cmd, write_concern : WriteConcern | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, server_description : SDAM::ServerDescription | Nil = nil, session : Session::ClientSession | Nil = nil, operation_id : Int64 | Nil = nil, **args) #

Execute a command on the server.

# First argument is the `Mongo::Commands`.
client.command(Mongo::Commands::DropDatabase, database: "database_name")

def database(name : String) : Database #

Get a newly allocated Mongo::Database for the database named name.


def default_auth_db : String #

The default auth database is optionally provided as a part of the connection string uri.

see: https://docs.mongodb.com/manual/reference/connection-string/


def default_database : Database | Nil #

Get a newly allocated Mongo::Databaseusing the default auth database string optionally provided as a part of the connection string uri.

see: https://docs.mongodb.com/manual/reference/connection-string/


def list_databases(*, filter = nil, name_only : Bool | Nil = nil, authorized_databases : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::ListDatabases::Result #

Provides a list of all existing databases along with basic statistics about them.

NOTE for more details, please check the official MongoDB documentation.


def options : Options #

The set of driver options.


def read_concern : ReadConcern | Nil #

Read concern accessor.

See: the official documentation


def read_concern=(read_concern : ReadConcern | Nil) #

Read concern accessor.

See: the official documentation


def read_preference : ReadPreference | Nil #

ReadPreference accessor.

See: the official documentation.


def read_preference=(read_preference : ReadPreference | Nil) #

ReadPreference accessor.

See: the official documentation.


def start_session(*, causal_consistency : Bool = true, default_transaction_options : Session::TransactionOptions | Nil = nil) : Session::ClientSession #

Starts a new logical session for a sequence of operations.

client = Mongo::Client.new

# First, create a ClientSession which is by default causally consistent.
session = client.start_session
collection = client["db"]["coll"]

# On a side note, it is important to ensure that both read and writes are performed with "majority" concern.
collection.read_concern = Mongo::ReadConcern.new(level: "majority")
collection.write_concern = Mongo::WriteConcern.new(w: "majority")

# Then pass session as the *session* named argument…
collection.insert_one({a: 1}, session: session)
collection.find_one({a: 1}, session: session)

# …and always end the session after using it.
session.end

def status(*, repl : Int32 | Nil = nil, metrics : Int32 | Nil = nil, locks : Int32 | Nil = nil, mirrored_reads : Int32 | Nil = nil, latch_analysis : Int32 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil #

Returns a document that provides an overview of the database’s state.

NOTE for more details, please check the official MongoDB documentation.


def subscribe_commands(&callback : Monitoring::Commands::Event -> Nil) : Monitoring::Commands::Event -> Nil #

Subscribe to monitoring command events.

client = Mongo::Client.new

client.subscribe_commands { |event|
  case event
  when Mongo::Monitoring::Commands::CommandStartedEvent
    Log.info { "COMMAND.#{event.command_name} #{event.address} STARTED: #{event.command.to_json}" }
  when Mongo::Monitoring::Commands::CommandSucceededEvent
    Log.info { "COMMAND.#{event.command_name} #{event.address} COMPLETED: #{event.reply.to_json} (#{event.duration}s)" }
  when Mongo::Monitoring::Commands::CommandFailedEvent
    Log.info { "COMMAND.#{event.command_name} #{event.address} FAILED: #{event.failure.inspect} (#{event.duration}s)" }
  end
}

def top : BSON | Nil #

An administrative command that returns usage statistics for each collection.

NOTE for more details, please check the official MongoDB documentation.


def unsubscribe_commands(callback : Monitoring::Commands::Event -> Nil) : Nil #

Ends the subscription for command events.

client = Mongo::Client.new

subscription = client.subscribe_commands { |event|
  puts event
}

client.unsubscribe_commands(subscription)

def watch(pipeline : Array = [] of BSON, *, full_document : String | Nil = nil, resume_after : BSON | Nil = nil, max_await_time_ms : Int64 | Nil = nil, batch_size : Int32 | Nil = nil, collation : Collation | Nil = nil, start_at_operation_time : Time | Nil = nil, start_after : BSON | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Mongo::ChangeStream::Cursor #

Allows a client to observe all changes in a cluster.

Returns a change stream on all collections in all databases in a cluster.

NOTE Excludes system collections.


def write_concern : WriteConcern | Nil #

Write concern accessor.

See: the official documentation


def write_concern=(write_concern : WriteConcern | Nil) #

Write concern accessor.

See: the official documentation