Class: Mongo::Client
- Inherits:
-
Object
- Object
- Mongo::Client
- Extended by:
- Forwardable
- Includes:
- Loggable
- Defined in:
- 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_connecting, :max_idle_time, :max_pool_size, :max_read_retries, :max_write_retries, :min_pool_size, :monitoring, :monitoring_io, :password, :platform, :populator_io, :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.
- #closed? ⇒ Boolean
- #cluster_options ⇒ Object private
-
#database_names(filter = {}, opts = {}) ⇒ Array<String>
Get the names of all databases.
-
#encrypted_fields_map ⇒ Hash | nil
private
Returns encrypted field map hash if provided when creating the client.
-
#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.
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 597 598 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 'lib/mongo/client.rb', line 496 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.close rescue => e log_warn("Eror closing 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.
138 139 140 |
# File 'lib/mongo/client.rb', line 138 def cluster @cluster end |
#database ⇒ Mongo::Database (readonly)
Returns database The database the client is operating on.
141 142 143 |
# File 'lib/mongo/client.rb', line 141 def database @database end |
#encrypter ⇒ Mongo::Crypt::AutoEncrypter (readonly)
Returns The object that encapsulates auto-encryption behavior.
148 149 150 |
# File 'lib/mongo/client.rb', line 148 def encrypter @encrypter end |
#options ⇒ Hash (readonly)
Returns options The configuration options.
144 145 146 |
# File 'lib/mongo/client.rb', line 144 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.
1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 |
# File 'lib/mongo/client.rb', line 1168 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.
177 178 179 180 |
# File 'lib/mongo/client.rb', line 177 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.
194 195 196 |
# File 'lib/mongo/client.rb', line 194 def [](collection_name, = {}) database[collection_name, ] end |
#close ⇒ true
Close all connections.
879 880 881 882 883 884 885 |
# File 'lib/mongo/client.rb', line 879 def close @connect_lock.synchronize do @closed = true do_close end true end |
#close_encrypter ⇒ true
Close encrypter and clean up auto-encryption resources.
890 891 892 893 894 |
# File 'lib/mongo/client.rb', line 890 def close_encrypter @encrypter.close if @encrypter true end |
#closed? ⇒ Boolean
870 871 872 |
# File 'lib/mongo/client.rb', line 870 def closed? !!@closed 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.
625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 |
# File 'lib/mongo/client.rb', line 625 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.
943 944 945 |
# File 'lib/mongo/client.rb', line 943 def database_names(filter = {}, opts = {}) list_databases(filter, true, opts).collect{ |info| info['name'] } end |
#encrypted_fields_map ⇒ Hash | 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 encrypted field map hash if provided when creating the client.
1184 1185 1186 |
# File 'lib/mongo/client.rb', line 1184 def encrypted_fields_map @encrypted_fields_map ||= @options.fetch(:auto_encryption_options, {})[:encrypted_fields_map] 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.
1124 1125 1126 1127 1128 |
# File 'lib/mongo/client.rb', line 1124 def get_session( = {}) get_session!() rescue Error::SessionsNotSupported nil end |
#hash ⇒ Integer
Get the hash value of the client.
206 207 208 |
# File 'lib/mongo/client.rb', line 206 def hash [cluster, ].hash end |
#inspect ⇒ String
Get an inspection of the client as a string.
688 689 690 |
# File 'lib/mongo/client.rb', line 688 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.
969 970 971 972 973 974 975 |
# File 'lib/mongo/client.rb', line 969 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.
992 993 994 995 996 |
# File 'lib/mongo/client.rb', line 992 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.
656 657 658 |
# File 'lib/mongo/client.rb', line 656 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.
676 677 678 |
# File 'lib/mongo/client.rb', line 676 def max_write_retries [:max_write_retries] || Cluster::MAX_WRITE_RETRIES end |
#read_concern ⇒ Hash
Get the read concern for this client.
853 854 855 |
# File 'lib/mongo/client.rb', line 853 def read_concern [:read_concern] end |
#read_preference ⇒ BSON::Document
Get the read preference from the options passed to the client.
736 737 738 |
# File 'lib/mongo/client.rb', line 736 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.
666 667 668 |
# File 'lib/mongo/client.rb', line 666 def read_retry_interval [:read_retry_interval] || Cluster::READ_RETRY_INTERVAL end |
#reconnect ⇒ true
Reconnect the client.
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 |
# File 'lib/mongo/client.rb', line 904 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 @closed = false 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.
714 715 716 717 718 719 720 |
# File 'lib/mongo/client.rb', line 714 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.
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 |
# File 'lib/mongo/client.rb', line 1017 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.
700 701 702 |
# File 'lib/mongo/client.rb', line 700 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).
803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 |
# File 'lib/mongo/client.rb', line 803 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.
755 756 757 |
# File 'lib/mongo/client.rb', line 755 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.
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 |
# File 'lib/mongo/client.rb', line 1094 def watch(pipeline = [], = {}) return use(Database::ADMIN).watch(pipeline, ) unless database.name == Database::ADMIN = .dup [:await_data] = true if [:max_await_time_ms] 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.
777 778 779 780 781 782 783 784 785 786 787 |
# File 'lib/mongo/client.rb', line 777 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, monitoring: opts[:monitoring]) 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.
1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 |
# File 'lib/mongo/client.rb', line 1150 def with_session( = {}, &block) # TODO: Add this back in RUBY-3174. # assert_not_closed 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.
866 867 868 |
# File 'lib/mongo/client.rb', line 866 def write_concern @write_concern ||= WriteConcern.get([:write_concern] || [:write]) end |