mongo-ruby-driver/lib/mongo/db.rb
2009-11-17 13:20:57 -05:00

679 lines
23 KiB
Ruby

# --
# Copyright (C) 2008-2009 10gen Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ++
require 'socket'
require 'digest/md5'
require 'thread'
require 'mongo/collection'
require 'mongo/util/ordered_hash.rb'
require 'mongo/admin'
module Mongo
# A Mongo database.
class DB
STANDARD_HEADER_SIZE = 16
RESPONSE_HEADER_SIZE = 20
SYSTEM_NAMESPACE_COLLECTION = "system.namespaces"
SYSTEM_INDEX_COLLECTION = "system.indexes"
SYSTEM_PROFILE_COLLECTION = "system.profile"
SYSTEM_USER_COLLECTION = "system.users"
SYSTEM_COMMAND_COLLECTION = "$cmd"
# Counter for generating unique request ids.
@@current_request_id = 0
# Strict mode enforces collection existence checks. When +true+,
# asking for a collection that does not exist or trying to create a
# collection that already exists raises an error.
#
# Strict mode is off (+false+) by default. Its value can be changed at
# any time.
attr_writer :strict
# Returns the value of the +strict+ flag.
def strict?; @strict; end
# The name of the database.
attr_reader :name
attr_reader :connection
# Host to which we are currently connected.
attr_reader :host
# Port to which we are currently connected.
attr_reader :port
# An array of [host, port] pairs.
attr_reader :nodes
# The database's socket. For internal (and Cursor) use only.
attr_reader :socket
# The logger instance if :logger is passed to initialize
attr_reader :logger
def slave_ok?; @slave_ok; end
def auto_reconnect?; @auto_reconnect; end
# A primary key factory object (or +nil+). See the README.doc file or
# DB#new for details.
attr_reader :pk_factory
def pk_factory=(pk_factory)
raise "error: can not change PK factory" if @pk_factory
@pk_factory = pk_factory
end
# Instances of DB are normally obtained by calling Mongo#db.
#
# db_name :: The database name
#
# nodes :: An array of [host, port] pairs. See Connection#new, which offers
# a more flexible way of defining nodes.
#
# options :: A hash of options.
#
# Options:
#
# :strict :: If true, collections must exist to be accessed and must
# not exist to be created. See #collection and
# #create_collection.
#
# :pk :: A primary key factory object that must respond to :create_pk,
# which should take a hash and return a hash which merges the
# original hash with any primary key fields the factory wishes
# to inject. (NOTE: if the object already has a primary key,
# the factory should not inject a new key; this means that the
# object is being used in a repsert but it already exists.) The
# idea here is that when ever a record is inserted, the :pk
# object's +create_pk+ method will be called and the new hash
# returned will be inserted.
#
# :slave_ok :: Only used if +nodes+ contains only one host/port. If
# false, when connecting to that host/port we check to
# see if the server is the master. If it is not, an error
# is thrown.
#
# :auto_reconnect :: If the connection gets closed (for example, we
# have a server pair and saw the "not master"
# error, which closes the connection), then
# automatically try to reconnect to the master or
# to the single server we have been given. Defaults
# to +false+.
# :logger :: Optional Logger instance to which driver usage information
# will be logged.
#
# When a DB object first connects to a pair, it will find the master
# instance and connect to that one. On socket error or if we recieve a
# "not master" error, we again find the master of the pair.
def initialize(db_name, nodes, options={})
case db_name
when Symbol, String
else
raise TypeError, "db_name must be a string or symbol"
end
[" ", ".", "$", "/", "\\"].each do |invalid_char|
if db_name.include? invalid_char
raise InvalidName, "database names cannot contain the character '#{invalid_char}'"
end
end
if db_name.empty?
raise InvalidName, "database name cannot be the empty string"
end
@connection = options[:connection]
@name, @nodes = db_name, nodes
@strict = options[:strict]
@pk_factory = options[:pk]
@slave_ok = options[:slave_ok] && @nodes.length == 1 # only OK if one node
@auto_reconnect = options[:auto_reconnect]
@semaphore = Mutex.new
@socket = nil
@logger = options[:logger]
connect_to_master
end
def connect_to_master
close if @socket
@host = @port = nil
@nodes.detect { |hp|
@host, @port = *hp
begin
@socket = TCPSocket.new(@host, @port)
@socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
# Check for master. Can't call master? because it uses mutex,
# which may already be in use during this call.
semaphore_is_locked = @semaphore.locked?
@semaphore.unlock if semaphore_is_locked
is_master = master?
@semaphore.lock if semaphore_is_locked
if !@slave_ok && !is_master
raise ConfigurationError, "Trying to connect directly to slave; if this is what you want, specify :slave_ok => true."
end
@slave_ok || is_master
rescue SocketError, SystemCallError, IOError => ex
close if @socket
false
end
}
raise "error: failed to connect to any given host:port" unless @socket
end
# Returns true if +username+ has +password+ in
# +SYSTEM_USER_COLLECTION+. +name+ is username, +password+ is
# plaintext password.
def authenticate(username, password)
doc = db_command(:getnonce => 1)
raise "error retrieving nonce: #{doc}" unless ok?(doc)
nonce = doc['nonce']
auth = OrderedHash.new
auth['authenticate'] = 1
auth['user'] = username
auth['nonce'] = nonce
auth['key'] = Digest::MD5.hexdigest("#{nonce}#{username}#{hash_password(username, password)}")
ok?(db_command(auth))
end
# Deauthorizes use for this database for this connection.
def logout
doc = db_command(:logout => 1)
raise "error logging out: #{doc.inspect}" unless ok?(doc)
end
# Returns an array of collection names in this database.
def collection_names
names = collections_info.collect { |doc| doc['name'] || '' }
names = names.delete_if {|name| name.index(@name).nil? || name.index('$')}
names.map {|name| name.sub(@name + '.', '')}
end
# Retruns an array of Collection instances, one for each collection in this
# database.
def collections
collection_names.map do |collection_name|
Collection.new(self, collection_name)
end
end
# Returns a cursor over query result hashes. Each hash contains a
# 'name' string and optionally an 'options' hash. If +coll_name+ is
# specified, an array of length 1 is returned.
def collections_info(coll_name=nil)
selector = {}
selector[:name] = full_collection_name(coll_name) if coll_name
Cursor.new(Collection.new(self, SYSTEM_NAMESPACE_COLLECTION), :selector => selector)
end
# Create a collection. If +strict+ is false, will return existing or
# new collection. If +strict+ is true, will raise an error if
# collection +name+ already exists.
#
# Options is an optional hash:
#
# :capped :: Boolean. If not specified, capped is +false+.
#
# :size :: If +capped+ is +true+, specifies the maximum number of
# bytes. If +false+, specifies the initial extent of the
# collection.
#
# :max :: Max number of records in a capped collection. Optional.
def create_collection(name, options={})
# First check existence
if collection_names.include?(name)
if strict?
raise "Collection #{name} already exists. Currently in strict mode."
else
return Collection.new(self, name)
end
end
# Create new collection
oh = OrderedHash.new
oh[:create] = name
doc = db_command(oh.merge(options || {}))
ok = doc['ok']
return Collection.new(self, name, @pk_factory) if ok.kind_of?(Numeric) && (ok.to_i == 1 || ok.to_i == 0)
raise "Error creating collection: #{doc.inspect}"
end
def admin
Admin.new(self)
end
# Return a collection. If +strict+ is false, will return existing or
# new collection. If +strict+ is true, will raise an error if
# collection +name+ does not already exists.
def collection(name)
return Collection.new(self, name, @pk_factory) if !strict? || collection_names.include?(name)
raise "Collection #{name} doesn't exist. Currently in strict mode."
end
alias_method :[], :collection
# Drop collection +name+. Returns +true+ on success or if the
# collection does not exist, +false+ otherwise.
def drop_collection(name)
return true unless collection_names.include?(name)
ok?(db_command(:drop => name))
end
# Returns the error message from the most recently executed database
# operation for this connection, or +nil+ if there was no error.
def error
doc = db_command(:getlasterror => 1)
raise "error retrieving last error: #{doc}" unless ok?(doc)
doc['err']
end
# Get status information from the last operation on this connection.
def last_status
db_command(:getlasterror => 1)
end
# Returns +true+ if an error was caused by the most recently executed
# database operation.
def error?
error != nil
end
# Get the most recent error to have occured on this database
#
# Only returns errors that have occured since the last call to
# DB#reset_error_history - returns +nil+ if there is no such error.
def previous_error
error = db_command(:getpreverror => 1)
if error["err"]
error
else
nil
end
end
# Reset the error history of this database
#
# Calls to DB#previous_error will only return errors that have occurred
# since the most recent call to this method.
def reset_error_history
db_command(:reseterror => 1)
end
# Returns true if this database is a master (or is not paired with any
# other database), false if it is a slave.
def master?
doc = db_command(:ismaster => 1)
is_master = doc['ismaster']
ok?(doc) && is_master.kind_of?(Numeric) && is_master.to_i == 1
end
# Returns a string of the form "host:port" that points to the master
# database. Works even if this is the master database.
def master
doc = db_command(:ismaster => 1)
is_master = doc['ismaster']
raise "Error retrieving master database: #{doc.inspect}" unless ok?(doc) && is_master.kind_of?(Numeric)
case is_master.to_i
when 1
"#@host:#@port"
else
doc['remote']
end
end
# Close the connection to the database.
def close
if @socket
s = @socket
@socket = nil
s.close
end
end
def connected?
@socket != nil
end
def receive_full(length)
message = ""
while message.length < length do
chunk = @socket.recv(length - message.length)
raise "connection closed" unless chunk.length > 0
message += chunk
end
message
end
# Returns a Cursor over the query results.
#
# Note that the query gets sent lazily; the cursor calls
# #send_query_message when needed. If the caller never requests an
# object from the cursor, the query never gets sent.
def query(collection, query, admin=false)
Cursor.new(self, collection, query, admin)
end
# Dereference a DBRef, getting the document it points to.
def dereference(dbref)
collection(dbref.namespace).find_one("_id" => dbref.object_id)
end
# Evaluate a JavaScript expression on MongoDB.
# +code+ should be a string or Code instance containing a JavaScript
# expression. Additional arguments will be passed to that expression
# when it is run on the server.
def eval(code, *args)
if not code.is_a? Code
code = Code.new(code)
end
oh = OrderedHash.new
oh[:$eval] = code
oh[:args] = args
doc = db_command(oh)
return doc['retval'] if ok?(doc)
raise OperationFailure, "eval failed: #{doc['errmsg']}"
end
# Rename collection +from+ to +to+. Meant to be called by
# Collection#rename.
def rename_collection(from, to)
oh = OrderedHash.new
oh[:renameCollection] = "#{@name}.#{from}"
oh[:to] = "#{@name}.#{to}"
doc = db_command(oh, true)
raise "Error renaming collection: #{doc.inspect}" unless ok?(doc)
end
# Drop index +name+ from +collection_name+. Normally called from
# Collection#drop_index or Collection#drop_indexes.
def drop_index(collection_name, name)
oh = OrderedHash.new
oh[:deleteIndexes] = collection_name
oh[:index] = name
doc = db_command(oh)
raise "Error with drop_index command: #{doc.inspect}" unless ok?(doc)
end
# Get information on the indexes for the collection +collection_name+.
# Normally called by Collection#index_information. Returns a hash where
# the keys are index names (as returned by Collection#create_index and
# the values are lists of [key, direction] pairs specifying the index
# (as passed to Collection#create_index).
def index_information(collection_name)
sel = {:ns => full_collection_name(collection_name)}
info = {}
Cursor.new(Collection.new(self, SYSTEM_INDEX_COLLECTION), :selector => sel).each { |index|
info[index['name']] = index['key'].map
}
info
end
# Create a new index on +collection_name+. +field_or_spec+
# should be either a single field name or a Array of [field name,
# direction] pairs. Directions should be specified as
# Mongo::ASCENDING or Mongo::DESCENDING. Normally called
# by Collection#create_index. If +unique+ is true the index will
# enforce a uniqueness constraint.
def create_index(collection_name, field_or_spec, unique=false)
self.collection(collection_name).create_index(field_or_spec, unique)
end
# Sends a message to MongoDB.
#
# Takes a MongoDB opcode, +operation+, a message of class ByteBuffer,
# +message+, and an optional formatted +log_message+.
# Sends the message to the databse, adding the necessary headers.
def send_message_with_operation(operation, message, log_message=nil)
message_with_headers = add_message_headers(operation, message).to_s
@logger.debug(" MONGODB #{log_message || message}") if @logger
@semaphore.synchronize do
send_message_on_socket(message_with_headers)
end
end
def send_message_with_operation_raw(operation, message, log_message=nil)
message_with_headers = add_message_headers_raw(operation, message)
@logger.debug(" MONGODB #{log_message || message}") if @logger
@semaphore.synchronize do
send_message_on_socket(message_with_headers)
end
end
# Sends a message to the database, waits for a response, and raises
# and exception if the operation has failed.
def send_message_with_safe_check(operation, message, log_message=nil)
message_with_headers = add_message_headers(operation, message)
message_with_check = last_error_message
@logger.debug(" MONGODB #{log_message || message}") if @logger
@semaphore.synchronize do
send_message_on_socket(message_with_headers.append!(message_with_check).to_s)
docs, num_received, cursor_id = receive
if num_received == 1 && error = docs[0]['err']
raise Mongo::OperationFailure, error
end
end
end
# Send a message to the database and waits for the response.
def receive_message_with_operation(operation, message, log_message=nil)
message_with_headers = add_message_headers(operation, message).to_s
@logger.debug(" MONGODB #{log_message || message}") if @logger
@semaphore.synchronize do
send_message_on_socket(message_with_headers)
receive
end
end
# Return +true+ if +doc+ contains an 'ok' field with the value 1.
def ok?(doc)
ok = doc['ok']
ok.kind_of?(Numeric) && ok.to_i == 1
end
# DB commands need to be ordered, so selector must be an OrderedHash
# (or a Hash with only one element). What DB commands really need is
# that the "command" key be first.
def db_command(selector, use_admin_db=false)
if !selector.kind_of?(OrderedHash)
if !selector.kind_of?(Hash) || selector.keys.length > 1
raise "db_command must be given an OrderedHash when there is more than one key"
end
end
cursor = Cursor.new(Collection.new(self, SYSTEM_COMMAND_COLLECTION), :admin => use_admin_db, :limit => -1, :selector => selector)
cursor.next_object
end
# Sends a command to the database.
#
# :selector (required) :: An OrderedHash, or a standard Hash with just one
# key, specifying the command to be performed.
#
# :admin (optional) :: If true, the command will be executed on the admin
# collection.
#
# :check_response (optional) :: If true, will raise an exception if the
# command fails.
#
# Note: DB commands must start with the "command" key. For this reason,
# any selector containing more than one key must be an OrderedHash.
def command(selector, admin=false, check_response=false)
raise MongoArgumentError, "command must be given a selector" unless selector.is_a?(Hash) && !selector.empty?
if selector.class.eql?(Hash) && selector.keys.length > 1
raise MongoArgumentError, "DB#command requires an OrderedHash when hash contains multiple keys"
end
result = Cursor.new(system_command_collection, :admin => admin,
:limit => -1, :selector => selector).next_object
if check_response && !ok?(result)
raise OperationFailure, "Database command '#{selector.keys.first}' failed."
else
result
end
end
def full_collection_name(collection_name)
"#{@name}.#{collection_name}"
end
private
def receive
receive_header
number_received, cursor_id = receive_response_header
read_documents(number_received, cursor_id)
end
def receive_header
header = ByteBuffer.new
header.put_array(receive_data_on_socket(16).unpack("C*"))
unless header.size == STANDARD_HEADER_SIZE
raise "Short read for DB response header: " +
"expected #{STANDARD_HEADER_SIZE} bytes, saw #{header.size}"
end
header.rewind
size = header.get_int
request_id = header.get_int
response_to = header.get_int
op = header.get_int
end
def receive_response_header
header_buf = ByteBuffer.new
header_buf.put_array(receive_data_on_socket(RESPONSE_HEADER_SIZE).unpack("C*"))
if header_buf.length != RESPONSE_HEADER_SIZE
raise "Short read for DB response header; " +
"expected #{RESPONSE_HEADER_SIZE} bytes, saw #{header_buf.length}"
end
header_buf.rewind
result_flags = header_buf.get_int
cursor_id = header_buf.get_long
starting_from = header_buf.get_int
number_remaining = header_buf.get_int
[number_remaining, cursor_id]
end
def read_documents(number_received, cursor_id)
docs = []
number_remaining = number_received
while number_remaining > 0 do
buf = ByteBuffer.new
buf.put_array(receive_data_on_socket(4).unpack("C*"))
buf.rewind
size = buf.get_int
buf.put_array(receive_data_on_socket(size - 4).unpack("C*"), 4)
number_remaining -= 1
buf.rewind
docs << BSON.new.deserialize(buf)
end
[docs, number_received, cursor_id]
end
# Sending a message on socket.
def send_message_on_socket(packed_message)
connect_to_master if !connected? && @auto_reconnect
begin
@socket.print(packed_message)
@socket.flush
rescue => ex
close
raise ex
end
end
# Receive data of specified length on socket.
def receive_data_on_socket(length)
message = ""
while message.length < length do
chunk = @socket.recv(length - message.length)
raise "connection closed" unless chunk.length > 0
message += chunk
end
message
end
# Prepares a message for transmission to MongoDB by
# constructing a valid message header.
def add_message_headers(operation, message)
headers = ByteBuffer.new
# Message size.
headers.put_int(16 + message.size)
# Unique request id.
headers.put_int(get_request_id)
# Response id.
headers.put_int(0)
# Opcode.
headers.put_int(operation)
message.prepend!(headers)
end
# Increments and then returns the next available request id.
# Note: this method should be called from within a lock.
def get_request_id
@@current_request_id += 1
@@current_request_id
end
# Creates a getlasterror message.
def last_error_message
generate_last_error_message
end
def generate_last_error_message
message = ByteBuffer.new
message.put_int(0)
BSON.serialize_cstr(message, "#{@name}.$cmd")
message.put_int(0)
message.put_int(-1)
message.put_array(BSON_SERIALIZER.serialize({:getlasterror => 1}, false).unpack("C*"))
add_message_headers(Mongo::Constants::OP_QUERY, message)
end
def reset_error_message
@@reset_error_message ||= generate_reset_error_message
end
def generate_reset_error_message
message = ByteBuffer.new
message.put_int(0)
BSON.serialize_cstr(message, "#{@name}.$cmd")
message.put_int(0)
message.put_int(-1)
message.put_array(BSON_SERIALIZER.serialize({:reseterror => 1}, false).unpack("C*"))
add_message_headers(Mongo::Constants::OP_QUERY, message)
end
def hash_password(username, plaintext)
Digest::MD5.hexdigest("#{username}:mongo:#{plaintext}")
end
def system_command_collection
Collection.new(self, SYSTEM_COMMAND_COLLECTION)
end
end
end