Sedna XML database client library¶ ↑

This library provides a Ruby client for Sedna, an open-source, native XML database system. The client is a Ruby extension that uses the official C driver that is shipped as part of the Sedna distribution.

Browse the Ruby API documentation online at http://sedna.rubyforge.org/doc

Sedna provides a full range of core database services – persistent storage, ACID transactions, security, indices, hot backup. Flexible XML processing facilities include W3C XQuery implementation, tight integration of XQuery with full-text search facilities and a node-level update language.

For more information about the Sedna XML database system, see the project page at modis.ispras.ru/sedna

Author: Rolf Timmermans (r.timmermans at voormedia.com)

Copyright 2008-2010 Voormedia B.V.

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

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.

The current version of this library is 0.6.0. This is a stable release. For a complete overview all recent and previous changes, see CHANGES.rdoc.

The Sedna client library ships with a copy of the official C driver, which will be built for your platform automatically when you install it.

The library has been tested with Ruby 1.8.6 and above, including Ruby 1.9.1 and Ruby 1.9.2.

Install the Ruby client library as a gem.

% gem install sedna

If you do not wish to use the bundled driver, you have the option to use a version installed on your system. You can specify in which location the library and header files located by adding the --with-sedna-dir option when installing.

% gem install sedna -- --with-sedna-dir=/path/to/sedna

After installation, require the sedna library in order to start using it.

require "rubygems"
require "sedna"

To start querying a database, create a new connection with the Sedna.connect method. When a block is given, the Sedna connection object will be returned which can be used to execute database statements. See the documentation of the Sedna class for more details.

connection_details = {
  :database => "my_db",
  :host => "localhost",
  :username => "SYSTEM",
  :password => "MANAGER",
}

Sedna.connect connection_details do |sedna|
  # Start querying the database.
  sedna.execute "create document 'my_doc'"                                  #=> nil
  sedna.execute "update insert <msg>Hello world!</msg> into doc('my_doc')"  #=> nil
  sedna.execute "doc('my_doc')/msg/text()"                                  #=> ["Hello world!"]
  # The connection is closed automatically for us.
end

Use Sedna#load_document to load a document into the database from a string or file.

sedna.load_document "<msg>Hello world!</msg>", "my_doc", "my_collection"
sedna.execute "doc('my_doc', 'my_collection')/msg/text()"                   #=> ["Hello world!"]

File.open "document.xml" do |file|
  sedna.load_document file, "my_doc2", "my_collection"
end

Use Sedna#transaction to wrap multiple database statements in a transaction. This ensures that either all or none of these statements are executed. If something goes wrong halfway, the previously executed statements that are part of the transaction will be rolled back.

sedna.transaction do
  amount = 100
  sedna.execute "update replace $balance in doc('my_account')/balance
                 with <balance>{$balance - #{amount}}</balance>"
  sedna.execute "update replace $balance in doc('your_account')/balance
                 with <balance>{$balance + #{amount}}</balance>"
  # If the second statement fails, the first will be rolled back. Only if
  # both statements succeed will the changes become permanent.
end

For detailed usage information, see http://sedna.rubyforge.org/doc