Class: Mongo::URI

Inherits:
Object
  • Object
show all
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.(uri.credentials)
client[uri.database]

Since:

  • 2.0.0

Direct Known Subclasses

SRVProtocol

Defined Under Namespace

Classes: OptionsMapper, SRVProtocol

Constant Summary collapse

SCHEME =
Deprecated.

Will be removed in 3.0.

The mongodb connection string scheme.

Since:

  • 2.0.0

'mongodb://'.freeze
MONGODB_SCHEME =

The mongodb connection string scheme root.

Since:

  • 2.5.0

'mongodb'.freeze
MONGODB_SRV_SCHEME =

The mongodb srv protocol connection string scheme root.

Since:

  • 2.5.0

'mongodb+srv'.freeze
INVALID_SCHEME =
Deprecated.

Error details for an invalid scheme.

Since:

  • 2.1.0

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

MongoDB URI format specification.

Since:

  • 2.0.0

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

MongoDB URI (connection string) documentation url

Since:

  • 2.0.0

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

Unsafe characters that must be urlencoded.

Since:

  • 2.1.0

/[\:\/\@]/
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

','.freeze
HOST_PORT_DELIM =

The character separating a host and port.

Since:

  • 2.1.0

':'.freeze
DATABASE_DELIM =

The character delimiting a database.

Since:

  • 2.1.0

'/'.freeze
URI_OPTS_DELIM =

The character delimiting options.

Since:

  • 2.1.0

'?'.freeze
INDIV_URI_OPTS_DELIM =
Deprecated.

The character delimiting multiple options.

Since:

  • 2.1.0

'&'.freeze
URI_OPTS_VALUE_DELIM =

The character delimiting an option and its value.

Since:

  • 2.1.0

'='.freeze
AUTH_USER_PWD_DELIM =

The character separating a username from the password.

Since:

  • 2.1.0

':'.freeze
AUTH_DELIM =

The character delimiting auth credentials.

Since:

  • 2.1.0

'@'.freeze
SCHEME_DELIM =

Scheme delimiter.

Since:

  • 2.5.0

'://'.freeze
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}'".freeze
UNESCAPED_USER_PWD =

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

Since:

  • 2.1.0

"User name and password must be urlencoded.".freeze
UNESCAPED_UNIX_SOCKET =

Error details for a non-urlencoded unix socket path.

Since:

  • 2.1.0

"UNIX domain sockets must be urlencoded.".freeze
UNESCAPED_DATABASE =

Error details for a non-urlencoded auth database name.

Since:

  • 2.1.0

"Auth database must be urlencoded.".freeze
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.".freeze
INVALID_HOST =

Error details for a missing host.

Since:

  • 2.1.0

"Missing host; at least one must be provided.".freeze
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".freeze
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
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

[ :tag_sets, :ssl ]

Constants included from Loggable

Loggable::PREFIX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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:

Since:

  • 2.0.0



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/mongo/uri.rb', line 284

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

  @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
  if remaining.empty?
    raise_invalid_error!('No hosts in the URI')
  end
  parse!(remaining)
  validate_uri_options!
end

Instance Attribute Details

#options ⇒ Object (readonly)

The uri parser object options.

Since:

  • 2.0.0



39
40
41
 
# File 'lib/mongo/uri.rb', line 39

def options
  @options
end

#servers ⇒ Object (readonly)

The servers specified in the uri.

Since:

  • 2.0.0



49
50
51
 
# File 'lib/mongo/uri.rb', line 49

def servers
  @servers
end

#uri_options ⇒ Object (readonly)

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

Since:

  • 2.1.0



44
45
46
 
# File 'lib/mongo/uri.rb', line 44

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:

Since:

  • 2.5.0



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/mongo/uri.rb', line 230

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

  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:

Since:

  • 2.0.0



259
260
261
262
263
264
265
 
# File 'lib/mongo/uri.rb', line 259

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



315
316
317
 
# File 'lib/mongo/uri.rb', line 315

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



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

def database
  @database ? @database : Database::ADMIN
end

#srv_records ⇒ Object

Since:

  • 2.0.0



267
268
269
 
# File 'lib/mongo/uri.rb', line 267

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



337
338
339
 
# File 'lib/mongo/uri.rb', line 337

def to_s
  reconstruct_uri
end