class Mongo::Client

• Mongo::Client
• Reference
• Object

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

• Mongo::WithReadConcern
• Mongo::WithReadPreference
• Mongo::WithWriteConcern

Defined in:

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

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

  Create a mongodb client instance from a mongodb URL.

Instance Method Summary

• #[](name : String) : Database

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

• #close

  Frees all the resources associated with a client.

• #cluster_time : Session::ClusterTime | Nil

  The current highest seen cluster time for the deployment

• #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.

• #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.

• #database(name : String) : Database

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

• #default_auth_db : String

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

• #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.

• #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.

• #options : Options

  The set of driver options.

• #read_concern : ReadConcern | Nil

  Read concern accessor.

• #read_concern=(read_concern : ReadConcern | Nil)

  Read concern accessor.

• #read_preference : ReadPreference | Nil

  ReadPreference accessor.

• #read_preference=(read_preference : ReadPreference | Nil)

  ReadPreference accessor.

• #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.

• #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.

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

  Subscribe to monitoring command events.

• #top : BSON | Nil

  An administrative command that returns usage statistics for each collection.

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

  Ends the subscription for command events.

• #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.

• #write_concern : WriteConcern | Nil

  Write concern accessor.

• #write_concern=(write_concern : WriteConcern | Nil)

  Write concern accessor.

Constructor Detail

require "cryomongo"

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

Instance Method Detail

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

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

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

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
}

client = Mongo::Client.new

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

client.unsubscribe_commands(subscription)