Class | Mongo::MongoClient |
In: |
lib/mongo/mongo_client.rb
|
Parent: | Object |
Instantiates and manages self.connections to MongoDB.
Mutex | = | ::Mutex |
ConditionVariable | = | ::ConditionVariable |
DEFAULT_HOST | = | 'localhost' |
DEFAULT_PORT | = | 27017 |
DEFAULT_DB_NAME | = | 'test' |
GENERIC_OPTS | = | [:ssl, :auths, :logger, :connect] |
TIMEOUT_OPTS | = | [:timeout, :op_timeout, :connect_timeout] |
POOL_OPTS | = | [:pool_size, :pool_timeout] |
READ_PREFERENCE_OPTS | = | [:read, :tag_sets, :secondary_acceptable_latency_ms] |
WRITE_CONCERN_OPTS | = | [:w, :j, :fsync, :wtimeout] |
CLIENT_ONLY_OPTS | = | [:slave_ok] |
acceptable_latency | [R] | |
auths | [R] | |
connect_timeout | [R] | |
host_to_try | [R] | |
logger | [R] | |
op_timeout | [R] | |
pool_size | [R] | |
pool_timeout | [R] | |
primary | [R] | |
primary_pool | [R] | |
read | [R] | |
size | [R] | |
socket_class | [R] | |
tag_sets | [R] | |
write_concern | [R] |
Initialize a connection to MongoDB using the MongoDB URI spec.
Since MongoClient.new cannot be used with any ENV["MONGODB_URI"] that has multiple hosts (implying a replicaset), you may use this when the type of your connection varies by environment and should be determined solely from ENV["MONGODB_URI"].
@param uri [String]
A string of the format mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/database]
@param opts Any of the options available for MongoClient.new
@return [Mongo::MongoClient, Mongo::MongoReplicaSetClient]
DEPRECATED
Initialize a connection to a MongoDB replica set using an array of seed nodes.
The seed nodes specified will be used on the initial connection to the replica set, but note that this list of nodes will be replaced by the list of canonical nodes returned by running the is_master command on the replica set.
@param nodes [Array] An array of arrays, each of which specifies a host and port. @param opts [Hash] Any of the available options that can be passed to MongoClient.new.
@option opts [String] :rs_name (nil) The name of the replica set to connect to. An exception will be
raised if unable to connect to a replica set with this name.
@option opts [Boolean] :read_secondary (false) When true, this connection object will pick a random slave
to send reads to.
@example
Mongo::MongoClient.multi([["db1.example.com", 27017], ["db2.example.com", 27017]])
@example This connection will read from a random secondary node.
Mongo::MongoClient.multi([["db1.example.com", 27017], ["db2.example.com", 27017], ["db3.example.com", 27017]], :read_secondary => true)
@return [Mongo::MongoClient]
@deprecated
Create a connection to single MongoDB instance.
If no args are provided, it will check ENV["MONGODB_URI"].
You may specify whether connection to slave is permitted. In all cases, the default host is "localhost" and the default port is 27017.
If you‘re connecting to a replica set, you‘ll need to use MongoReplicaSetClient.new instead.
Once connected to a replica set, you can find out which nodes are primary, secondary, and arbiters with the corresponding accessors: MongoClient#primary, MongoClient#secondaries, and MongoClient#arbiters. This is useful if your application needs to connect manually to nodes other than the primary.
@param [String] host @param [Integer] port specify a port number here if only one host is being specified.
@option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
should be acknowledged
@option opts [Boolean] :j (false) Set journal acknowledgement @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
Notes about write concern options: Write concern options are propagated to objects instantiated from this MongoClient. These defaults can be overridden upon instantiation of any object by explicitly setting an options hash on initialization.
@option opts [Boolean] :slave_ok (false) Must be set to true when connecting
to a single, slave node.
@option opts [Logger, debug] :logger (nil) A Logger instance for debugging driver ops. Note that
logging negatively impacts performance; therefore, it should not be used for high-performance apps.
@option opts [Integer] :pool_size (1) The maximum number of socket self.connections allowed per
connection pool. Note: this setting is relevant only for multi-threaded applications.
@option opts [Float] :timeout (5.0) When all of the self.connections a pool are checked out,
this is the number of seconds to wait for a new connection to be released before throwing an exception. Note: this setting is relevant only for multi-threaded applications (which in Ruby are rare).
@option opts [Float] :op_timeout (nil) The number of seconds to wait for a read operation to time out.
Disabled by default.
@option opts [Float] :connect_timeout (nil) The number of seconds to wait before timing out a
connection attempt.
@option opts [Boolean] :ssl (false) If true, create the connection to the server using SSL.
@example localhost, 27017 (or ENV["MONGODB_URI"] if available)
MongoClient.new
@example localhost, 27017
MongoClient.new("localhost")
@example localhost, 3000, max 5 self.connections, with max 5 seconds of wait time.
MongoClient.new("localhost", 3000, :pool_size => 5, :timeout => 5)
@example localhost, 3000, where this node may be a slave
MongoClient.new("localhost", 3000, :slave_ok => true)
@example Unix Domain Socket
MongoClient.new("/var/run/mongodb.sock")
@see api.mongodb.org/ruby/current/file.REPLICA_SETS.html Replica sets in Ruby
@raise [ReplicaSetConnectionError] This is raised if a replica set name is specified and the
driver fails to connect to a replica set with that name.
@raise [MongoArgumentError] If called with no arguments and ENV["MONGODB_URI"] implies a replica set.
@core self.connections
Determine if the connection is active. In a normal case the server_info operation will be performed without issues, but if the connection was dropped by the server or for some reason the sockets are unsynchronized, a ConnectionFailure will be raised and the return will be false.
@return [Boolean]
Save an authentication to this connection. When connecting, the connection will attempt to re-authenticate on every db specified in the list of auths. This method is called automatically by DB#authenticate.
Note: this method will not actually issue an authentication command. To do that, either run MongoClient#apply_saved_authentication or DB#authenticate.
@param [String] db_name @param [String] username @param [String] password
@return [Hash] a hash representing the authentication just added.
Apply each of the saved database authentications.
@return [Boolean] returns true if authentications exist and succeeds, false
if none exists.
@raise [AuthenticationError] raises an exception if any one
authentication fails.
Check a socket back into its pool. Note: this is overridden in MongoReplicaSetClient.
Checkout a socket for reading (i.e., a secondary node). Note: this is overridden in MongoReplicaSetClient.
Checkout a socket for writing (i.e., a primary node). Note: this is overridden in MongoReplicaSetClient.
Remove all authentication information stored in this connection.
@return [true] this operation return true because it always succeeds.
Create a new socket and attempt to connect to master. If successful, sets host and port to master and returns the socket.
If connecting to a replica set, this method will replace the initially-provided seed list with any nodes known to the set.
@raise [ConnectionFailure] if unable to connect to any host or port.
It‘s possible that we defined connected as all nodes being connected??? NOTE: Do check if this needs to be more stringent. Probably not since if any node raises a connection failure, all nodes will be closed.
Copy the database from to to on localhost. The from database is assumed to be on localhost, but an alternate host can be specified.
@param [String] from name of the database to copy from. @param [String] to name of the database to copy to. @param [String] from_host host of the ‘from’ database. @param [String] username username for authentication against from_db (>=1.3.x). @param [String] password password for authentication against from_db (>=1.3.x).
Return a hash with all database names and their respective sizes on disk.
@return [Hash]
Fsync, then lock the mongod process against writes. Use this to get the datafiles in a state safe for snapshotting, backing up, etc.
@return [BSON::OrderedHash] the command response
Returns the maximum BSON object size as returned by the core server. Use the 4MB default when the server doesn‘t report this.
@return [Integer]
Checks if a server is alive. This command will return immediately even if the server is in a lock.
@return [Hash]
Ensures that the alias carries over to the overridden connect method when using the replica set or sharded clients.
Determine whether we‘re reading from a primary node. If false, this connection connects to a secondary node and @slave_ok is true.
@return [Boolean]
Ensures that the alias carries over to the overridden connect method when using the replica set or sharded clients.
Get the build version of the current server.
@return [Mongo::ServerVersion]
object allowing easy comparability of version.