Class: Mongo::Client
- Inherits:
-
Object
- Object
- Mongo::Client
- Extended by:
- Forwardable
- Includes:
- Loggable
- Defined in:
- build/ruby-driver-master/lib/mongo/client.rb
Overview
The client is the entry point to the driver and is the main object that will be interacted with.
Constant Summary collapse
- CRUD_OPTIONS =
The options that do not affect the behavior of a cluster and its subcomponents.
[ :auto_encryption_options, :database, :read, :read_concern, :write, :write_concern, :retry_reads, :max_read_retries, :read_retry_interval, :retry_writes, :max_write_retries, # Options which cannot currently be here: # # :server_selection_timeout # Server selection timeout is used by cluster constructor to figure out # how long to wait for initial scan in compatibility mode, but once # the cluster is initialized it no longer uses this timeout. # Unfortunately server selector reads server selection timeout out of # the cluster, and this behavior is required by Cluster#next_primary # which takes no arguments. When next_primary is removed we can revsit # using the same cluster object with different server selection timeouts. ].freeze
- VALID_OPTIONS =
Valid client options.
[ :app_name, :auth_mech, :auth_mech_properties, :auth_source, :auto_encryption_options, :bg_error_backtrace, :cleanup, :compressors, :direct_connection, :connect, :connect_timeout, :database, :heartbeat_frequency, :id_generator, :load_balanced, :local_threshold, :logger, :log_prefix, :max_idle_time, :max_pool_size, :max_read_retries, :max_write_retries, :min_pool_size, :monitoring, :monitoring_io, :password, :platform, :read, :read_concern, :read_retry_interval, :replica_set, :resolv_options, :retry_reads, :retry_writes, :scan, :sdam_proc, :server_api, :server_selection_timeout, :socket_timeout, :srv_max_hosts, :srv_service_name, :ssl, :ssl_ca_cert, :ssl_ca_cert_object, :ssl_ca_cert_string, :ssl_cert, :ssl_cert_object, :ssl_cert_string, :ssl_key, :ssl_key_object, :ssl_key_pass_phrase, :ssl_key_string, :ssl_verify, :ssl_verify_certificate, :ssl_verify_hostname, :ssl_verify_ocsp_endpoint, :truncate_logs, :user, :wait_queue_timeout, :wrapping_libraries, :write, :write_concern, :zlib_compression_level, ].freeze
- VALID_COMPRESSORS =
The compression algorithms supported by the driver.
[ Mongo::Protocol::Compressed::ZSTD, Mongo::Protocol::Compressed::SNAPPY, Mongo::Protocol::Compressed::ZLIB ].freeze
- VALID_SERVER_API_VERSIONS =
The known server API versions.
%w( 1 ).freeze
Constants included from Loggable
Instance Attribute Summary collapse
-
#cluster ⇒ Mongo::Cluster
readonly
Cluster The cluster of servers for the client.
-
#database ⇒ Mongo::Database
readonly
Database The database the client is operating on.
-
#encrypter ⇒ Mongo::Crypt::AutoEncrypter
readonly
The object that encapsulates auto-encryption behavior.
-
#options ⇒ Hash
readonly
Options The configuration options.
Class Method Summary collapse
-
.canonicalize_ruby_options(options) ⇒ Object
private
Lowercases auth mechanism properties, if given, in the specified options, then converts the options to an instance of Options::Redacted.
Instance Method Summary collapse
-
#==(other) ⇒ true, false
(also: #eql?)
Determine if this client is equivalent to another object.
-
#[](collection_name, options = {}) ⇒ Mongo::Collection
Get a collection object for the provided collection name.
-
#close ⇒ true
Close all connections.
-
#close_encrypter ⇒ true
Close encrypter and clean up auto-encryption resources.
- #cluster_options ⇒ Object private
-
#database_names(filter = {}, opts = {}) ⇒ Array<String>
Get the names of all databases.
-
#get_session(options = {}) ⇒ Session | nil
private
Returns a session to use for operations if possible.
-
#hash ⇒ Integer
Get the hash value of the client.
-
#initialize(addresses_or_uri, options = nil) ⇒ Client
constructor
Instantiate a new driver client.
-
#inspect ⇒ String
Get an inspection of the client as a string.
-
#list_databases(filter = {}, name_only = false, opts = {}) ⇒ Array<Hash>
Get info for each database.
-
#list_mongo_databases(filter = {}, opts = {}) ⇒ Array<Mongo::Database>
Returns a list of Mongo::Database objects.
-
#max_read_retries ⇒ Integer
private
Get the maximum number of times the client can retry a read operation when using legacy read retries.
-
#max_write_retries ⇒ Integer
private
Get the maximum number of times the client can retry a write operation when using legacy write retries.
-
#read_concern ⇒ Hash
Get the read concern for this client.
-
#read_preference ⇒ BSON::Document
Get the read preference from the options passed to the client.
-
#read_retry_interval ⇒ Float
private
Get the interval, in seconds, in which read retries when using legacy read retries.
-
#reconnect ⇒ true
Reconnect the client.
-
#server_selector ⇒ Mongo::ServerSelector
Get the server selector.
-
#start_session(options = {}) ⇒ Session
Start a session.
-
#summary ⇒ String
Get a summary of the client state.
-
#update_options(new_options) ⇒ Hash
private
Updates this client’s options from new_options, validating all options.
-
#use(name) ⇒ Mongo::Client
Creates a new client configured to use the database with the provided name, and using the other options configured in this client.
-
#watch(pipeline = [], options = {}) ⇒ ChangeStream
As of version 3.6 of the MongoDB server, a “$changeStream“ pipeline stage is supported in the aggregation framework.
-
#with(new_options = nil) ⇒ Mongo::Client
Creates a new client with the passed options merged over the existing options of this client.
-
#with_session(options = {}, &block) ⇒ Object
private
Creates a session to use for operations if possible and yields it to the provided block.
-
#write_concern ⇒ Mongo::WriteConcern
Get the write concern for this client.
Methods included from Loggable
#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger
Constructor Details
#initialize(addresses_or_uri, options = nil) ⇒ Client
Instantiate a new driver client.
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 470 def initialize(addresses_or_uri, = nil) = ? .dup : {} srv_uri = nil if addresses_or_uri.is_a?(::String) uri = URI.get(addresses_or_uri, ) if uri.is_a?(URI::SRVProtocol) # If the URI is an SRV URI, note this so that we can start # SRV polling if the topology is a sharded cluster. srv_uri = uri end addresses = uri.servers = uri..dup # Special handing for :write and :write_concern: allow client Ruby # options to override URI options, even when the Ruby option uses the # deprecated :write key and the URI option uses the current # :write_concern key if [:write] .delete(:write_concern) end = .merge() @srv_records = uri.srv_records else addresses = addresses_or_uri addresses.each do |addr| if addr =~ /\Amongodb(\+srv)?:\/\//i raise ArgumentError, "Host '#{addr}' should not contain protocol. Did you mean to not use an array?" end end @srv_records = nil end = self.class.() # The server API version is specified to be a string. # However, it is very annoying to always provide the number 1 as a string, # therefore cast to the string type here. if server_api = [:server_api] if server_api.is_a?(Hash) server_api = Options::Redacted.new(server_api) if (version = server_api[:version]).is_a?(Integer) [:server_api] = server_api.merge(version: version.to_s) end end end # Special handling for sdam_proc as it is only used during client # construction sdam_proc = .delete(:sdam_proc) # For gssapi service_name, the default option is given in a hash # (one level down from the top level). = () .each do |k, v| default_v = [k] if Hash === default_v v = default_v.merge(v) end [k] = v end = .keys.each do |k| if [k].nil? .delete(k) end end @options = () =begin WriteConcern object support if @options[:write_concern].is_a?(WriteConcern::Base) # Cache the instance so that we do not needlessly reconstruct it. @write_concern = @options[:write_concern] @options[:write_concern] = @write_concern.options end =end @options.freeze (addresses, is_srv: uri.is_a?(URI::SRVProtocol)) = @options.dup .delete(:server_api) @database = Database.new(self, @options[:database], ) # Temporarily set monitoring so that event subscriptions can be # set up without there being a cluster @monitoring = Monitoring.new(@options) if sdam_proc sdam_proc.call(self) end @connect_lock = Mutex.new @connect_lock.synchronize do @cluster = Cluster.new(addresses, @monitoring, .merge(srv_uri: srv_uri)) end begin # Unset monitoring, it will be taken out of cluster from now on remove_instance_variable('@monitoring') if @options[:auto_encryption_options] @connect_lock.synchronize do build_encrypter end end rescue begin @cluster.disconnect! rescue => e log_warn("Eror disconnecting cluster in client constructor's exception handler: #{e.class}: #{e}") # Drop this exception so that the original exception is raised end raise end if block_given? begin yield(self) ensure close end end end |
Instance Attribute Details
#cluster ⇒ Mongo::Cluster (readonly)
Returns cluster The cluster of servers for the client.
136 137 138 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 136 def cluster @cluster end |
#database ⇒ Mongo::Database (readonly)
Returns database The database the client is operating on.
139 140 141 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 139 def database @database end |
#encrypter ⇒ Mongo::Crypt::AutoEncrypter (readonly)
Returns The object that encapsulates auto-encryption behavior.
146 147 148 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 146 def encrypter @encrypter end |
#options ⇒ Hash (readonly)
Returns options The configuration options.
142 143 144 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 142 def @options end |
Class Method Details
.canonicalize_ruby_options(options) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Lowercases auth mechanism properties, if given, in the specified options, then converts the options to an instance of Options::Redacted.
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 1102 def () Options::Redacted.new(Hash[.map do |k, v| if k == :auth_mech_properties || k == 'auth_mech_properties' if v v = Hash[v.map { |pk, pv| [pk.downcase, pv] }] end end [k, v] end]) end |
Instance Method Details
#==(other) ⇒ true, false Also known as: eql?
Determine if this client is equivalent to another object.
175 176 177 178 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 175 def ==(other) return false unless other.is_a?(Client) cluster == other.cluster && == other. end |
#[](collection_name, options = {}) ⇒ Mongo::Collection
Get a collection object for the provided collection name.
192 193 194 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 192 def [](collection_name, = {}) database[collection_name, ] end |
#close ⇒ true
Close all connections.
849 850 851 852 853 854 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 849 def close @connect_lock.synchronize do do_close end true end |
#close_encrypter ⇒ true
Close encrypter and clean up auto-encryption resources.
859 860 861 862 863 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 859 def close_encrypter @encrypter.close if @encrypter true end |
#cluster_options ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 599 def # We share clusters when a new client with different CRUD_OPTIONS # is requested; therefore, cluster should not be getting any of these # options upon instantiation .reject do |key, value| CRUD_OPTIONS.include?(key.to_sym) end.merge( # but need to put the database back in for auth... database: [:database], # Put these options in for legacy compatibility, but note that # their values on the client and the cluster do not have to match - # applications should read these values from client, not from cluster max_read_retries: [:max_read_retries], read_retry_interval: [:read_retry_interval], ).tap do || # If the client has a cluster already, forward srv_uri to the new # cluster to maintain SRV monitoring. If the client is brand new, # its constructor sets srv_uri manually. if cluster .update(srv_uri: cluster.[:srv_uri]) end end end |
#database_names(filter = {}, opts = {}) ⇒ Array<String>
Get the names of all databases.
910 911 912 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 910 def database_names(filter = {}, opts = {}) list_databases(filter, true, opts).collect{ |info| info['name'] } end |
#get_session(options = {}) ⇒ Session | nil
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns a session to use for operations if possible.
If :session option is set, validates that session and returns it. Otherwise, if deployment supports sessions, creates a new session and returns it. When a new session is created, the session will be implicit (lifecycle is managed by the driver) if the :implicit option is given, otherwise the session will be explicit (lifecycle managed by the application). If deployment does not support session, returns nil.
1061 1062 1063 1064 1065 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 1061 def get_session( = {}) get_session!() rescue Error::SessionsNotSupported nil end |
#hash ⇒ Integer
Get the hash value of the client.
204 205 206 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 204 def hash [cluster, ].hash end |
#inspect ⇒ String
Get an inspection of the client as a string.
662 663 664 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 662 def inspect "#<Mongo::Client:0x#{object_id} cluster=#{cluster.summary}>" end |
#list_databases(filter = {}, name_only = false, opts = {}) ⇒ Array<Hash>
Get info for each database.
936 937 938 939 940 941 942 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 936 def list_databases(filter = {}, name_only = false, opts = {}) cmd = { listDatabases: 1 } cmd[:nameOnly] = !!name_only cmd[:filter] = filter unless filter.empty? cmd[:authorizedDatabases] = true if opts[:authorized_databases] use(Database::ADMIN).database.read_command(cmd, opts).first[Database::DATABASES] end |
#list_mongo_databases(filter = {}, opts = {}) ⇒ Array<Mongo::Database>
Returns a list of Mongo::Database objects.
959 960 961 962 963 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 959 def list_mongo_databases(filter = {}, opts = {}) database_names(filter, opts).collect do |name| Database.new(self, name, ) end end |
#max_read_retries ⇒ Integer
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Get the maximum number of times the client can retry a read operation when using legacy read retries.
630 631 632 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 630 def max_read_retries [:max_read_retries] || Cluster::MAX_READ_RETRIES end |
#max_write_retries ⇒ Integer
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Get the maximum number of times the client can retry a write operation when using legacy write retries.
650 651 652 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 650 def max_write_retries [:max_write_retries] || Cluster::MAX_WRITE_RETRIES end |
#read_concern ⇒ Hash
Get the read concern for this client.
827 828 829 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 827 def read_concern [:read_concern] end |
#read_preference ⇒ BSON::Document
Get the read preference from the options passed to the client.
710 711 712 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 710 def read_preference @read_preference ||= [:read] end |
#read_retry_interval ⇒ Float
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Get the interval, in seconds, in which read retries when using legacy read retries.
640 641 642 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 640 def read_retry_interval [:read_retry_interval] || Cluster::READ_RETRY_INTERVAL end |
#reconnect ⇒ true
Reconnect the client.
873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 873 def reconnect addresses = cluster.addresses.map(&:to_s) @connect_lock.synchronize do do_close rescue nil @cluster = Cluster.new(addresses, monitoring, ) if @options[:auto_encryption_options] build_encrypter end end true end |
#server_selector ⇒ Mongo::ServerSelector
Get the server selector. It either uses the read preference defined in the client options or defaults to a Primary server selector.
688 689 690 691 692 693 694 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 688 def server_selector @server_selector ||= if read_preference ServerSelector.get(read_preference) else ServerSelector.primary end end |
#start_session(options = {}) ⇒ Session
A Session cannot be used by multiple threads at once; session objects are not thread-safe.
Start a session.
If the deployment does not support sessions, raises Mongo::Error::InvalidSession. This exception can also be raised when the driver is not connected to a data-bearing server, for example during failover.
984 985 986 987 988 989 990 991 992 993 994 995 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 984 def start_session( = {}) session = get_session!(.merge(implicit: false)) if block_given? begin yield session ensure session.end_session end else session end end |
#summary ⇒ String
The exact format and layout of the returned summary string is not part of the driver’s public API and may be changed at any time.
Get a summary of the client state.
674 675 676 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 674 def summary "#<Client cluster=#{cluster.summary}>" end |
#update_options(new_options) ⇒ Hash
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Updates this client’s options from new_options, validating all options.
The new options may be transformed according to various rules. The final hash of options actually applied to the client is returned.
If options fail validation, this method may warn or raise an exception. If this method raises an exception, the client should be discarded (similarly to if a constructor raised an exception).
777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 777 def () = @options = self.class.( || {}) ().tap do |opts| # Our options are frozen = @options.dup if [:write] && opts[:write_concern] .delete(:write) end if [:write_concern] && opts[:write] .delete(:write_concern) end .update(opts) @options = .freeze = @options[:auto_encryption_options] != [:auto_encryption_options] # If there are new auto_encryption_options, create a new encrypter. # Otherwise, allow the new client to share an encrypter with the # original client. # # If auto_encryption_options are nil, set @encrypter to nil, but do not # close the encrypter because it may still be used by the original client. if @options[:auto_encryption_options] && @connect_lock.synchronize do build_encrypter end elsif @options[:auto_encryption_options].nil? @connect_lock.synchronize do @encrypter = nil end end end end |
#use(name) ⇒ Mongo::Client
The new client shares the cluster with the original client, and as a result also shares the monitoring instance and monitoring event subscribers.
Creates a new client configured to use the database with the provided name, and using the other options configured in this client.
729 730 731 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 729 def use(name) with(database: name) end |
#watch(pipeline = [], options = {}) ⇒ ChangeStream
A change stream only allows ‘majority’ read concern.
This helper method is preferable to running a raw aggregation with a $changeStream stage, for the purpose of supporting resumability.
As of version 3.6 of the MongoDB server, a “$changeStream“ pipeline stage is supported in the aggregation framework. As of version 4.0, this stage allows users to request that notifications are sent for all changes that occur in the client’s cluster.
1034 1035 1036 1037 1038 1039 1040 1041 1042 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 1034 def watch(pipeline = [], = {}) return use(Database::ADMIN).watch(pipeline, ) unless database.name == Database::ADMIN Mongo::Collection::View::ChangeStream.new( Mongo::Collection::View.new(self["#{Database::COMMAND}.aggregate"]), pipeline, Mongo::Collection::View::ChangeStream::CLUSTER, ) end |
#with(new_options = nil) ⇒ Mongo::Client
Depending on options given, the returned client may share the cluster with the original client or be created with a new cluster. If a new cluster is created, the monitoring event subscribers on the new client are set to the default event subscriber set and none of the subscribers on the original client are copied over.
Creates a new client with the passed options merged over the existing options of this client. Useful for one-offs to change specific options without altering the original client.
751 752 753 754 755 756 757 758 759 760 761 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 751 def with( = nil) clone.tap do |client| opts = client.( || Options::Redacted.new) Database.create(client) # We can't use the same cluster if some options that would affect it # have changed. if (opts) Cluster.create(client) end end end |
#with_session(options = {}, &block) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Creates a session to use for operations if possible and yields it to the provided block.
If :session option is set, validates that session and uses it. Otherwise, if deployment supports sessions, creates a new session and uses it. When a new session is created, the session will be implicit (lifecycle is managed by the driver) if the :implicit option is given, otherwise the session will be explicit (lifecycle managed by the application). If deployment does not support session, yields nil to the block.
When the block finishes, if the session was created and was implicit, or if an implicit session was passed in, the session is ended which returns it to the pool of available sessions.
1087 1088 1089 1090 1091 1092 1093 1094 1095 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 1087 def with_session( = {}, &block) session = get_session() yield session ensure if session && session.implicit? session.end_session end end |
#write_concern ⇒ Mongo::WriteConcern
Get the write concern for this client. If no option was provided, then a default single server acknowledgement will be used.
840 841 842 |
# File 'build/ruby-driver-master/lib/mongo/client.rb', line 840 def write_concern @write_concern ||= WriteConcern.get([:write_concern] || [:write]) end |