Class: Moped::Session

Inherits:
Object
  • Object
show all
Includes:
Optionable
Defined in:
lib/moped/session.rb

Overview

A session in moped is root for all interactions with a MongoDB server or replica set.

It can talk to a single default database, or dynamically speak to multiple databases.

Examples:

Single database (console-style)

session = Moped::Session.new(["127.0.0.1:27017"])
session.use(:moped)
session[:users].find.one

Multiple databases

session = Moped::Session.new(["127.0.0.1:27017"])
session.with(database: :admin) do |admin|
  admin.command(ismaster: 1)
end

Authentication

session = Moped::Session.new %w[127.0.0.1:27017],
session.with(database: "admin").("admin", "s3cr3t")

Since:

  • 1.0.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(seeds, options = {}) ⇒ Session

Initialize a new database session.

Examples:

Initialize a new session.

Session.new([ "localhost:27017" ])

Parameters:

  • seeds (Array) —

    An array of host:port pairs.

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

    The options for the session.

See Also:

  • options validations for allowed values in the options hash.

Since:

  • 1.0.0



264
265
266
267
268
 
# File 'lib/moped/session.rb', line 264

def initialize(seeds, options = {})
  validate_strict(options)
  @options = options
  @cluster = Cluster.new(seeds, options)
end

Instance Attribute Details

#cluster ⇒ Cluster

Returns The cluster of nodes.

Returns:

  • (Cluster) —

    The cluster of nodes.



40
41
42
 
# File 'lib/moped/session.rb', line 40

def cluster
  @cluster
end

#options ⇒ Object

Since:

  • 1.0.0



40
 
# File 'lib/moped/session.rb', line 40

attr_reader :cluster, :options

Class Method Details

.connect(uri) ⇒ Session

Create a new session from a URI.

Examples:

Initialize a new session.

Session.connect("mongodb://localhost:27017/my_db")

Parameters:

  • MongoDB (String) —

    URI formatted string.

Returns:

Since:

  • 3.0.0



405
406
407
408
409
410
 
# File 'lib/moped/session.rb', line 405

def connect(uri)
  uri = Uri.new(uri)
  session = new(*uri.moped_arguments)
  session.(uri.username, uri.password) if uri.auth_provided?
  session
end

Instance Method Details

#[](name) ⇒ Collection

Return collection from the current database.

Parameters:

  • collection (Symbol, String) —

    The collection name.

Returns:

Since:

  • 1.0.0



49
50
51
 
# File 'lib/moped/session.rb', line 49

def [](name)
  current_database[name]
end

#collection_names ⇒ Array<String>

Return non system collection name from the current database.

Returns:

  • (Array<String>) —

    The names of all collections.

Since:

  • 1.0.0



60
61
62
 
# File 'lib/moped/session.rb', line 60

def collection_names
  current_database.collection_names
end

#collections ⇒ Array<Collection>

Return non system collection name from the current database.

Returns:

Since:

  • 1.0.0



71
72
73
 
# File 'lib/moped/session.rb', line 71

def collections
  current_database.collections
end

#command(op) ⇒ Hash

Run command on the current database.

Parameters:

  • command (Hash) —

    The command to run.

Returns:

  • (Hash) —

    the result of the command.

Since:

  • 1.0.0



82
83
84
 
# File 'lib/moped/session.rb', line 82

def command(op)
  current_database.command(op)
end

#database_names ⇒ Array<String>

Note:

This requires admin access on your server.

Get a list of all the database names for the session.

Examples:

Get all the database names.

session.database_names

Returns:

  • (Array<String>) —

    All the database names.

Since:

  • 1.2.0



96
97
98
 
# File 'lib/moped/session.rb', line 96

def database_names
  databases["databases"].map { |database| database["name"] }
end

#databases ⇒ Hash

Note:

This requires admin access on your server.

Get information on all databases for the session. This includes the name, size on disk, and if it is empty or not.

Examples:

Get all the database information.

session.databases

Returns:

  • (Hash) —

    The hash of database information, under the “databases” key.

Since:

  • 1.2.0



112
113
114
 
# File 'lib/moped/session.rb', line 112

def databases
  with(database: :admin).command(listDatabases: 1)
end

#disconnect ⇒ true

Disconnects all nodes in the session’s cluster. This should only be used in cases # where you know you’re not going to use the cluster on the thread anymore and need to force the connections to close.

Returns:

  • (true) —

    True if the disconnect succeeded.

Since:

  • 1.2.0



123
124
125
 
# File 'lib/moped/session.rb', line 123

def disconnect
  cluster.disconnect
end

#drop ⇒ nil

Drop the current database.

Returns:

  • (nil) —

    nil.

Since:

  • 1.0.0



134
135
136
 
# File 'lib/moped/session.rb', line 134

def drop
  current_database.drop
end

#inspect ⇒ String

Provide a string inspection for the session.

Examples:

Inspect the session.

session.inspect

Returns:

  • (String) —

    The string inspection.

Since:

  • 1.4.0



146
147
148
 
# File 'lib/moped/session.rb', line 146

def inspect
  "<#{self.class.name} seeds=#{cluster.seeds} database=#{current_database_name}>"
end

#login(username, password) ⇒ Object

Log in with username and password on the current database.

Parameters:

  • username (String) —

    The username.

  • password (String) —

    The password.

Since:

  • 1.0.0



157
158
159
 
# File 'lib/moped/session.rb', line 157

def (username, password)
  current_database.(username, password)
end

#logout ⇒ Object

Log out from the current database.

Since:

  • 1.0.0



168
169
170
 
# File 'lib/moped/session.rb', line 168

def logout
  current_database.logout
end

#new(options = {}) {|session| ... } ⇒ Session

Create a new session with options and use new socket connections.

Examples:

Change safe mode

session.with(write: { w: 2 })[:people].insert(name: "Joe")

Change safe mode with block

session.with(write: { w: 2 }) do |session|
  session[:people].insert(name: "Joe")
end

Temporarily change database

session.with(database: "admin") do |admin|
  admin.command ismaster: 1
end

Copy between databases

session.use "moped"
session.with(database: "backup") do |backup|
  session[:people].each do |person|
    backup[:people].insert person
  end
end

Parameters:

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

    The options.

Yield Parameters:

  • session (Session) —

    The new session.

Returns:

See Also:

Since:

  • 1.0.0



302
303
304
305
306
307
308
309
310
 
# File 'lib/moped/session.rb', line 302

def new(options = {})
  session = with(options)
  session.instance_variable_set(:@cluster, cluster.dup)
  if block_given?
    yield(session)
  else
    session
  end
end

#read_preference ⇒ Object

Get the read preference for the session. Will default to primary if none was provided.

Examples:

Get the session’s read preference.

session.read_preference

Returns:

  • (Object) —

    The read preference.

Since:

  • 2.0.0



321
322
323
 
# File 'lib/moped/session.rb', line 321

def read_preference
  @read_preference ||= ReadPreference.get(options[:read] || :primary)
end

#use(database) ⇒ Object

Switch the session’s current database.

Examples:

Switch the current database.

session.use :moped
session[:people].find.one # => { :name => "John" }

Parameters:

  • database (String, Symbol) —

    The database to use.

Since:

  • 1.0.0



334
335
336
337
 
# File 'lib/moped/session.rb', line 334

def use(database)
  options[:database] = database
  set_current_database(database)
end

#with(options = {}) {|session| ... } ⇒ Session, Object

Create a new session with options reusing existing connections.

Examples:

Change safe mode

session.with(write: { w: 2 })[:people].insert(name: "Joe")

Change safe mode with block

session.with(write: { w: 2 }) do |session|
  session[:people].insert(name: "Joe")
end

Temporarily change database

session.with(database: "admin") do |admin|
  admin.command ismaster: 1
end

Copy between databases

session.use "moped"
session.with(database: "backup") do |backup|
  session[:people].each do |person|
    backup[:people].insert person
  end
end

Parameters:

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

    The session options.

Yield Parameters:

  • session (Session) —

    The new session.

Returns:

  • (Session, Object) —

    The new session, or the value returned by the block if provided.

Since:

  • 1.0.0



370
371
372
373
374
375
376
377
378
 
# File 'lib/moped/session.rb', line 370

def with(options = {})
  session = dup
  session.options.update(options)
  if block_given?
    yield(session)
  else
    session
  end
end

#write_concern ⇒ Object

Get the write concern for the session. Will default to propagate if none was provided.

Examples:

Get the session’s write concern.

session.write_concern

Returns:

  • (Object) —

    The write concern.

Since:

  • 2.0.0



389
390
391
 
# File 'lib/moped/session.rb', line 389

def write_concern
  @write_concern ||= WriteConcern.get(options[:write] || { w: 1 })
end