Class: Moped::Session

Inherits:
Object show all
Defined in:
lib/moped/session.rb,
lib/moped/session/context.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 # => { name: "John" }

Multiple databases

session = Moped::Session.new(["127.0.0.1:27017"])

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

session.with(database: :moped) do |moped|
  moped[:users].find.one # => { name: "John" }
end

Authentication


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

Defined Under Namespace

Classes: Context

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 of host:port pairs

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

Options Hash (options):

  • :safe (Boolean) — default: false —

    Ensure writes are persisted.

  • :safe (Hash) —

    Ensure writes are persisted with the specified safety level e.g., “fsync: true”, or “w: 2, wtimeout: 5”.

  • :database (Symbol, String) —

    The database to use.

  • :consistency (:strong, :eventual) — default: :eventual —

    .

  • :ssl (Boolean) —

    Connect using SSL.

  • :max_retries (Integer) —

    The maximum number of attempts to retry an operation. (30)

  • :retry_interval (Integer) —

    The time in seconds to retry connections to a secondary or primary after a failure. (1)

  • :timeout (Integer) —

    The time in seconds to wait for an operation to timeout. (5)

Since:

  • 1.0.0



201
202
203
204
205
206
 
# File 'lib/moped/session.rb', line 201

def initialize(seeds, options = {})
  @cluster = Cluster.new(seeds, options)
  @context = Context.new(self)
  @options = options
  @options[:consistency] ||= :eventual
end

Instance Attribute Details

#cluster ⇒ Object (readonly)

Returns the value of attribute cluster.



35
36
37
 
# File 'lib/moped/session.rb', line 35

def cluster
  @cluster
end

#cluster The session cluster.(Thesessioncluster.) ⇒ Object (readonly) 



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

attr_reader :cluster, :context, :options

#context ⇒ Object (readonly)

Returns the value of attribute context.



35
36
37
 
# File 'lib/moped/session.rb', line 35

def context
  @context
end

#context The session context.(Thesessioncontext.) ⇒ Object (readonly) 



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

attr_reader :cluster, :context, :options

#options ⇒ Object (readonly)

Returns the value of attribute options.



35
36
37
 
# File 'lib/moped/session.rb', line 35

def options
  @options
end

#options The session options.(Thesessionoptions.) ⇒ Object (readonly) 



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

attr_reader :cluster, :context, :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



342
343
344
345
346
347
 
# File 'lib/moped/session.rb', line 342

def connect(uri)
  uri = MongoUri.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:

Returns:

Since:

  • 1.0.0



44
45
46
 
# File 'lib/moped/session.rb', line 44

def [](name)
  current_database[name]
end

#collection_names ⇒ Array<String>

Return non system collection name from the current database.

Returns:

Since:

  • 1.0.0



55
56
57
 
# File 'lib/moped/session.rb', line 55

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



66
67
68
 
# File 'lib/moped/session.rb', line 66

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



77
78
79
 
# File 'lib/moped/session.rb', line 77

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

#consistency ⇒ :strong, :eventual

Get the session’s consistency.

Examples:

Get the session consistency.

session.consistency

Returns:

  • (:strong, :eventual) —

    The session’s consistency.

Since:

  • 1.0.0



175
176
177
 
# File 'lib/moped/session.rb', line 175

def consistency
  options[:consistency]
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:

Since:

  • 1.2.0



91
92
93
 
# File 'lib/moped/session.rb', line 91

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



107
108
109
 
# File 'lib/moped/session.rb', line 107

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



118
119
120
 
# File 'lib/moped/session.rb', line 118

def disconnect
  cluster.disconnect
end

#drop ⇒ nil

Drop the current database.

Returns:

  • (nil) —

    nil.

Since:

  • 1.0.0



129
130
131
 
# File 'lib/moped/session.rb', line 129

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



141
142
143
 
# File 'lib/moped/session.rb', line 141

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



152
153
154
 
# File 'lib/moped/session.rb', line 152

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

#logout ⇒ Object

Log out from the current database.

Since:

  • 1.0.0



163
164
165
 
# File 'lib/moped/session.rb', line 163

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(safe: { w: 2 })[:people].insert(name: "Joe")

Change safe mode with block

session.with(safe: { 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



240
241
242
243
244
245
246
247
248
 
# File 'lib/moped/session.rb', line 240

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

#safe? ⇒ true, false

Is the session operating in safe mode?

Examples:

Is the session operating in safe mode?

session.safe?

Returns:

  • (true, false) —

    Whether the current session requires safe operations.

Since:

  • 1.0.0



259
260
261
 
# File 'lib/moped/session.rb', line 259

def safe?
  !!safety
end

#safety ⇒ Boolean, Hash

Get the safety level for the session.

Examples:

Get the safety level.

session.safety

Returns:

  • (Boolean, Hash) —

    The safety level for this session.

Since:

  • 1.0.0



271
272
273
 
# File 'lib/moped/session.rb', line 271

def safety
  options[:safe].__safe_options__
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:

Since:

  • 1.0.0



284
285
286
287
 
# File 'lib/moped/session.rb', line 284

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(safe: { w: 2 })[:people].insert(name: "Joe")

Change safe mode with block

session.with(safe: { 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



320
321
322
323
324
325
326
327
328
 
# File 'lib/moped/session.rb', line 320

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