Class: Mongo::URI

Inherits:

Object

• Object
• Mongo::URI

Includes:

Address::Validator, Loggable

Defined in:

lib/mongo/uri.rb,
lib/mongo/uri/srv_protocol.rb,
lib/mongo/uri/options_mapper.rb

Overview

The URI class provides a way for users to parse the MongoDB uri as defined in the connection string format spec.

www.mongodb.com/docs/manual/reference/connection-string/

Examples:

Use the uri string to make a client connection.

uri = Mongo::URI.new('mongodb://localhost:27017')
client = Mongo::Client.new(uri.servers, uri.options)
client.login(uri.credentials)
client[uri.database]

Since:

• 2.0.0

Direct Known Subclasses

SRVProtocol

Defined Under Namespace

Classes: OptionsMapper, SRVProtocol

Constant Summary

SCHEME =

Deprecated.

Will be removed in 3.0.

The mongodb connection string scheme.

Since:

• 2.0.0

'mongodb://'

MONGODB_SCHEME =

The mongodb connection string scheme root.

Since:

• 2.5.0

'mongodb'

MONGODB_SRV_SCHEME =

The mongodb srv protocol connection string scheme root.

Since:

• 2.5.0

'mongodb+srv'

INVALID_SCHEME =

Deprecated.

Error details for an invalid scheme.

Since:

• 2.1.0

"Invalid scheme. Scheme must be '#{MONGODB_SCHEME}' or '#{MONGODB_SRV_SCHEME}'"

FORMAT =

MongoDB URI format specification.

Since:

• 2.0.0

'mongodb://[username:password@]host1[:port1][,host2[:port2]' +
',...[,hostN[:portN]]][/[database][?options]]'

HELP =

MongoDB URI (connection string) documentation url

Since:

• 2.0.0

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

UNSAFE =

Unsafe characters that must be urlencoded.

Since:

• 2.1.0

%r{[:/@]}

PERCENT_CHAR =

Percent sign that must be encoded in user creds.

Since:

• 2.5.1

/%/

UNIX_SOCKET =

Unix socket suffix.

Since:

• 2.1.0

/.sock/

HOST_DELIM =

The character delimiting hosts.

Since:

• 2.1.0

','

HOST_PORT_DELIM =

The character separating a host and port.

Since:

• 2.1.0

':'

DATABASE_DELIM =

The character delimiting a database.

Since:

• 2.1.0

'/'

URI_OPTS_DELIM =

The character delimiting options.

Since:

• 2.1.0

'?'

INDIV_URI_OPTS_DELIM =

Deprecated.

The character delimiting multiple options.

Since:

• 2.1.0

'&'

URI_OPTS_VALUE_DELIM =

The character delimiting an option and its value.

Since:

• 2.1.0

'='

AUTH_USER_PWD_DELIM =

The character separating a username from the password.

Since:

• 2.1.0

':'

AUTH_DELIM =

The character delimiting auth credentials.

Since:

• 2.1.0

'@'

SCHEME_DELIM =

Scheme delimiter.

Since:

• 2.5.0

'://'

INVALID_OPTS_VALUE_DELIM =

Error details for an invalid options format.

Since:

• 2.1.0

'Options and their values must be delimited' +
" by '#{URI_OPTS_VALUE_DELIM}'"

UNESCAPED_USER_PWD =

Error details for an non-urlencoded user name or password.

Since:

• 2.1.0

'User name and password must be urlencoded.'

UNESCAPED_UNIX_SOCKET =

Error details for a non-urlencoded unix socket path.

Since:

• 2.1.0

'UNIX domain sockets must be urlencoded.'

UNESCAPED_DATABASE =

Error details for a non-urlencoded auth database name.

Since:

• 2.1.0

'Auth database must be urlencoded.'

INVALID_OPTS_DELIM =

Error details for providing options without a database delimiter.

Since:

• 2.1.0

"Database delimiter '#{DATABASE_DELIM}' must be present if options are specified."

INVALID_HOST =

Error details for a missing host.

Since:

• 2.1.0

'Missing host; at least one must be provided.'

INVALID_PORT =

Error details for an invalid port.

Since:

• 2.1.0

'Invalid port. Port must be an integer greater than 0 and less than 65536'

READ_MODE_MAP =

Map of URI read preference modes to Ruby driver read preference modes

Since:

• 2.0.0

{
  'primary' => :primary,
  'primarypreferred' => :primary_preferred,
  'secondary' => :secondary,
  'secondarypreferred' => :secondary_preferred,
  'nearest' => :nearest
}.freeze

AUTH_MECH_MAP =

Map of URI authentication mechanisms to Ruby driver mechanisms

Since:

• 2.0.0

{
  'GSSAPI' => :gssapi,
  'MONGODB-AWS' => :aws,
  # MONGODB-CR is deprecated and will be removed in driver version 3.0
  'MONGODB-CR' => :mongodb_cr,
  'MONGODB-X509' => :mongodb_x509,
  'PLAIN' => :plain,
  'SCRAM-SHA-1' => :scram,
  'SCRAM-SHA-256' => :scram256,
}.freeze

SERVER_MONITORING_MODES =

Valid values for the serverMonitoringMode URI option.

Since:

• 2.0.0

%w[stream poll auto].freeze

REPEATABLE_OPTIONS =

Options that are allowed to appear more than once in the uri.

In order to follow the URI options spec requirement that all instances of ‘tls’ and ‘ssl’ have the same value, we need to keep track of all of the values passed in for those options. Assuming they don’t conflict, they will be condensed to a single value immediately after parsing the URI.

Since:

• 2.1.0

%i[tag_sets ssl]

Constants included from Loggable

Loggable::PREFIX

Instance Attribute Summary

• #options ⇒ Object readonly

  The uri parser object options.

• #servers ⇒ Object readonly

  The servers specified in the uri.

• #uri_options ⇒ Object readonly

  Mongo::Options::Redacted of the options specified in the uri.

Class Method Summary

• .get(string, opts = {}) ⇒ URI, URI::SRVProtocol

  Get either a URI object or a SRVProtocol URI object.

Instance Method Summary

• #client_options ⇒ Mongo::Options::Redacted

  Gets the options hash that needs to be passed to a Mongo::Client on instantiation, so we don’t have to merge the credentials and database in at that point - we only have a single point here.

• #credentials ⇒ Hash

  Get the credentials provided in the URI.

• #database ⇒ String

  Get the database provided in the URI.

• #initialize(string, options = {}) ⇒ URI constructor

  Create the new uri from the provided string.

• #srv_records ⇒ Object
• #to_s ⇒ String

  Get the uri as a string.

Methods included from Address::Validator

#validate_address_str!

Methods included from Loggable

#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger

Constructor Details

#initialize(string, options = {}) ⇒ URI

Create the new uri from the provided string.

Examples:

Create the new URI.

URI.new('mongodb://localhost:27017')

Parameters:

• string (String) —

  The URI to parse.

• options (Hash) (defaults to: {}) —

  The options.

Options Hash (options):

• :logger (Logger) —

  A custom logger to use.

Raises:

• (Error::InvalidURI) —

  If the uri does not match the spec.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 282

def initialize(string, options = {})
  raise Error::InvalidURI.new(string, 'URI must be a string, not nil.') unless string
  raise Error::InvalidURI.new(string, 'Cannot parse an empty URI.') if string.empty?

  @string = string
  @options = options
  parsed_scheme, _, remaining = string.partition(SCHEME_DELIM)
  unless parsed_scheme == scheme
    raise_invalid_error!("Invalid scheme '#{parsed_scheme}'. Scheme must be '#{MONGODB_SCHEME}'. Use URI#get to parse SRV URIs.")
  end
  raise_invalid_error!('No hosts in the URI') if remaining.empty?
  parse!(remaining)
  validate_uri_options!
end

Instance Attribute Details

#options ⇒ Object (readonly)

The uri parser object options.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 37

def options
  @options
end

#servers ⇒ Object (readonly)

The servers specified in the uri.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 47

def servers
  @servers
end

#uri_options ⇒ Object (readonly)

Mongo::Options::Redacted of the options specified in the uri.

Since:

• 2.1.0

# File 'lib/mongo/uri.rb', line 42

def uri_options
  @uri_options
end

Class Method Details

.get(string, opts = {}) ⇒ URI, URI::SRVProtocol

Get either a URI object or a SRVProtocol URI object.

Examples:

Get the uri object.

URI.get(string)

Parameters:

• string (String) —

  The URI to parse.

• opts (Hash) (defaults to: {}) —

  The options.

• options (Hash) —

  a customizable set of options

Returns:

• (URI, URI::SRVProtocol) —

  The uri object.

Raises:

• (Error::InvalidURI)

Since:

• 2.5.0

# File 'lib/mongo/uri.rb', line 231

def self.get(string, opts = {})
  raise Error::InvalidURI.new(string, 'URI must be a string, not nil.') unless string
  raise Error::InvalidURI.new(string, 'Cannot parse an empty URI.') if string.empty?

  scheme, = string.partition(SCHEME_DELIM)
  case scheme
  when MONGODB_SCHEME
    URI.new(string, opts)
  when MONGODB_SRV_SCHEME
    SRVProtocol.new(string, opts)
  else
    raise Error::InvalidURI.new(string,
                                "Invalid scheme '#{scheme}'. Scheme must be '#{MONGODB_SCHEME}' or '#{MONGODB_SRV_SCHEME}'")
  end
end

Instance Method Details

#client_options ⇒ Mongo::Options::Redacted

Gets the options hash that needs to be passed to a Mongo::Client on instantiation, so we don’t have to merge the credentials and database in at that point - we only have a single point here.

Examples:

Get the client options.

uri.client_options

Returns:

• (Mongo::Options::Redacted) —

  The options passed to the Mongo::Client

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 257

def client_options
  opts = uri_options.tap do |opts|
    opts[:database] = @database if @database
  end

  @user ? opts.merge(credentials) : opts
end

#credentials ⇒ Hash

Get the credentials provided in the URI.

Examples:

Get the credentials.

uri.credentials

Returns:

• (Hash) —

  The credentials.

  • :user [ String ] The user.

  • :password [ String ] The provided password.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 307

def credentials
  { user: @user, password: @password }
end

#database ⇒ String

Get the database provided in the URI.

Examples:

Get the database.

uri.database

Returns:

• (String) —

  The database.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 319

def database
  @database || Database::ADMIN
end

#srv_records ⇒ Object

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 265

def srv_records
  nil
end

#to_s ⇒ String

Get the uri as a string.

Examples:

Get the uri as a string.

uri.to_s

Returns:

• (String) —

  The uri string.

Since:

• 2.0.0

# File 'lib/mongo/uri.rb', line 329

def to_s
  reconstruct_uri
end