flexirecord 0.0.2

data/LICENSE

@@ -0,0 +1,23 @@
+# Copyright (c) 2007 FlexiGuided GmbH, Berlin
+#
+# Author: Jan Behrens
+#
+# Website: http://www.flexiguided.de/publications.flexirecord.en.html
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

data/flexirecord-demo.sql

@@ -0,0 +1,33 @@
+CREATE TABLE "person" (
+  "id"                  serial8         primary key,
+  "name"                text            not null );
+
+CREATE TABLE "medium" (
+  "number"              int8            primary key,
+  "lent_to_id"        int8              references "person" ("id")
+                                        on delete restrict on update cascade );
+
+CREATE TABLE "movie" (
+  "id"                  serial8         primary key,
+  "name"                text            not null );
+
+CREATE TABLE "medium_entry" (
+  "medium_number"       int8            not null references "medium" ("number")
+                                        on delete cascade on update cascade,
+  "position"            int8            not null,
+  "movie_id"            int8            not null
+                                        references "movie" ("id")
+                                        on delete restrict on update cascade,
+  PRIMARY KEY ("medium_number", "position") );
+
+CREATE TABLE "rating" (
+  "person_id"           int8            not null
+                                        references "person" ("id")
+                                        on delete cascade on update cascade,
+  "movie_id"            int8            not null
+                                        references "movie" ("id")
+                                        on delete cascade on update cascade,
+  "rating"              numeric,
+  "comment"             text,
+  PRIMARY KEY ("person_id", "movie_id") );
+

data/lib/flexirecord-demo.rb

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+
+require 'flexirecord'
+
+# Copyright (c) 2007 FlexiGuided GmbH, Berlin
+#
+# Author: Jan Behrens
+#
+# Website: http://www.flexiguided.de/publications.flexirecord.en.html
+#
+# -----
+#
+# Demonstration module for FlexiRecord.
+
+module FlexiRecordDemo
+
+  # FlexiRecord::ConnectionPool used for all models in this module.
+  ConnectionPool = FlexiRecord::BaseRecord.connection_pool = FlexiRecord::ConnectionPool.new(:engine => :postgresql, :db => 'moviedemo')
+
+  # A person (demo class).
+  #
+  # CREATE TABLE "person" ("id" serial8 primary key, "name" text not null );
+  class Person < FlexiRecord::BaseRecord
+    self.table_name = 'person'
+  end
+
+  # A Medium (demo class).
+  #
+  # CREATE TABLE "medium" ("number" int8 primary key, "lent_to_id" int8 references "person" ("id") on delete restrict on update cascade );
+  class Medium < FlexiRecord::BaseRecord
+    self.table_name = 'medium'
+    add_many_to_one_reference Person, ['lent_to_id', 'id'], :lent_to, :borrowed_media
+    def self.after_select(records)
+      super
+      records.preload(:entries).preload(:movie)
+      records.preload(:lent_to)
+      records.preload(:movies)
+    end
+    def save
+      if self.number == :auto
+        self.class.transaction self, :read_committed do
+          self.class.db_execute("LOCK TABLE #{self.class.table} IN SHARE ROW EXCLUSIVE MODE")
+          last_medium = Medium.select1('ORDER BY "number" DESC LIMIT 1')
+          self.number = if last_medium
+            last_medium.number + 1
+          else
+            1
+          end
+          return super
+        end
+      else
+        return super
+      end
+    end
+    def available?
+      lent_to.nil?
+    end
+  end
+
+  # A movie (demo class).
+  #
+  # CREATE TABLE "movie" ("id" serial8 primary key, "name" text not null );
+  class Movie < FlexiRecord::BaseRecord
+    self.table_name = 'movie'
+  end
+
+  # A medium entry (demo class).
+  #
+  # CREATE TABLE "medium_entry" ("medium_number" int8 not null references "medium" ("number") on delete cascade on update cascade, "position" int8 not null, "movie_id" int8 not null references "movie" ("id") on delete restrict on update cascade, PRIMARY KEY ("medium_number", "position") );
+  class MediumEntry < FlexiRecord::BaseRecord
+    include FlexiRecord::ListRecord
+    self.table_name = 'medium_entry'
+    add_many_to_one_reference(Medium, 'medium_', :medium, :entries).combine(
+      add_many_to_one_reference(Movie, 'movie_', :movie, :movie_entries),
+      :media, :movies
+    )
+    Medium.add_read_option :entries, :default, 'ORDER BY "position"'
+    Medium.add_read_option :movies,  :default, 'ORDER BY "rel"."position"'
+  end
+
+  # A rating entry (demo class).
+  #
+  # CREATE TABLE "rating" ("person_id" int8 not null references "person" ("id") on delete cascade on update cascade, "movie_id" int8 not null references "movie" ("id") on delete cascade on update cascade, "rating" numeric, "comment" text, PRIMARY KEY ("person_id", "movie_id") );
+  class Rating < FlexiRecord::Relationship
+    self.table_name = 'rating'
+    add_many_to_one_reference(Person, 'person_', :person, :ratings).combine(
+      add_many_to_one_reference(Movie, ['movie_id', 'id'], :movie, :ratings),
+      :rated_by, :rated_movies
+    )
+  end
+
+
+  # A small demonstration program. In order to be run, a database named 'moviedemo' has to be installed and initialized with the 'flexirecord-demo.sql' file, which is shipped with the software package.
+  def demo
+    # Creating demo entries
+    Person.transaction do
+      Rating.db_execute(     "DELETE FROM #{Rating.table}"     )
+      MediumEntry.db_execute("DELETE FROM #{MediumEntry.table}")
+      Movie.db_execute(      "DELETE FROM #{Movie.table}"      )
+      Medium.db_execute(     "DELETE FROM #{Medium.table}"     )
+      Person.db_execute(     "DELETE FROM #{Person.table}"     )
+    end
+    anja    = Person.new(:name => 'Anja'   ).save
+    phillip = Person.new(:name => 'Phillip').save
+    wilson  = Person.new(:name => 'Wilson' ).save
+    american_beauty = Movie.new(:name => 'American Beauty').save
+    naruto          = Movie.new(:name => 'Naruto').save
+    koyaanisqatsi   = Movie.new(:name => 'Koyaanisqatsi').save
+    medium_a = nil
+    Medium.transaction do
+      medium_a = Medium.new(:number => :auto).save
+      FlexiRecordDemo::MediumEntry.new(:medium => medium_a, :position => :last, :movie => naruto).save
+    end
+    medium_b = nil
+    Medium.transaction do
+      medium_b = Medium.new(:number => '42', :lent_to => phillip).save
+      MediumEntry.new(:medium => medium_b, :position => :last, :movie => koyaanisqatsi).save
+      MediumEntry.new(:medium => medium_b, :position => :last, :movie => american_beauty).save
+    end
+    Rating.new(:person => anja, :movie => naruto, :rating => Rational(7, 10)).save
+    Rating.new(:person => phillip, :movie => koyaanisqatsi, :rating => Rational(6,10)).save
+    Rating.new(:person => phillip, :movie => koyaanisqatsi, :rating => Rational(8,10)).save
+    Rating.new(:person => wilson, :movie => naruto, :comment => 'Rasengan!').save
+    # Some queries
+    person = Person.select1('WHERE "name" ILIKE $ ORDER BY "name" DESC LIMIT 1', 'P%')
+    puts "First person whose name is starting with 'P' is: #{person.name}."
+    puts "The following media are borrowed by him/her:"
+    person.borrowed_media.each do |medium|
+      puts "- ##{medium.number}"
+      medium.entries.each do |entry|
+        puts "  - #{entry.movie.name}"
+      end
+    end
+    puts "He rated the following movies:"
+    person.rated_movies.each do |movie|
+      rating = movie.rel
+      puts "- #{movie.name}"
+      puts "  - Rating: #{rating.rating ? rating.rating.to_s : 'none'}"
+      puts "  - Comment: #{rating.comment || 'none'}"
+    end
+    nil
+  end
+  module_function :demo
+
+end

data/lib/flexirecord.rb

@@ -0,0 +1,1425 @@
+#!/usr/bin/env ruby
+
+#--
+# Uncomment the following line to get debug output written to STDERR.
+#$flexirecord_debug_output = STDERR
+
+require 'postgres'
+require 'monitor'
+require 'thread_resource_pool'
+require 'rational'
+
+
+# Copyright (c) 2007 FlexiGuided GmbH, Berlin
+#
+# Author: Jan Behrens
+#
+# Website: http://www.flexiguided.de/publications.flexirecord.en.html
+#
+# -----
+#
+# FlexiRecord is a library for object oriented access to databases. Each table is represented by a class, each row of that table is represented by an object of that class. This library is especially aimed to properly support database transactions. By now only PostgreSQL (version 8.2 or higher!) is supported as a backend.
+#
+# Please note that this is an alpha release. This means the library is mostly untested yet. Use it at your own risk.
+#
+# To use FlexiRecord, you have to first create a new ConnectionPool with ConnectionPool.new. If all tables are stored on the same database, you can directly assign the ConnectionPool to the BaseRecord class, by calling:
+#
+# BaseRecord.connection_pool = ConnectionPool.new(...)
+#
+# You should also create sub-classes of BaseRecord, representing the tables of your database.
+#
+# There is a demonstration of the usage of this library in the flexirecord-demo.rb file (module FlexiRecordDemo).
+
+module FlexiRecord
+
+
+  # Quoted table alias used in SQL for the object to be selected.
+  DefaultTableAlias = '"obj"'.freeze
+
+  # Quoted table alias used in SQL for relationship entries in many-to-many relations.
+  RelationshipTableAlias = '"rel"'.freeze
+
+  # Property of objects fetched through many-to-many relations, which contain the relationship object.
+  RelationshipColumn = 'rel'.freeze
+
+
+  # Thrown when a database error occurs (e.g. constraint violation).
+
+  class DatabaseError < StandardError
+  end
+
+
+  # Transaction isolation levels are represented by (constant) IsolationLevel objects:
+  # - IsolationLevel::ReadUncommitted
+  #   (Data written by concurrent uncommitted transactions may be read.)
+  # - IsolationLevel::ReadCommitted 
+  #   (Only data, which has been committed by other transactions is read.)
+  # - IsolationLevel::RepeatableRead
+  # - IsolationLevel::Serializable
+  #   (The first query inside a transaction generates a "snapshot" of the database, which is then used for following read accesses.)
+
+  class IsolationLevel
+
+    include Comparable
+    private_class_method :new
+    @@symbols = {}
+
+    # Returns an IsolationLevel object, matching one of these symbols:
+    # - :read_uncommitted
+    # - :read_committed
+    # - :repeatable_read
+    # - :serializable
+    def self.by_symbol(symbol)
+      @@symbols[symbol.to_sym]
+    end
+
+    # Used for generating the 4 constants representing the possible isolation levels.
+    def initialize(integer, symbol, sql, name)
+      @integer = integer.to_i
+      @symbol  = symbol.to_sym
+      @sql     = sql.to_s.dup.freeze
+      @name    = name.to_s.dup.freeze
+      @@symbols[@symbol] = self
+      nil
+    end
+
+    # Returns the SQL string representation of the isolation level.
+    def to_s
+      @sql
+    end
+
+    # Returns an integer representing the isolation level, which is also used for comparing/ordering them.
+    def to_i
+      @integer
+    end
+
+    # Returns the name of the constant referring to the isolation level.
+    def inspect
+      "#{self.class.name}::#{@name}"
+    end
+
+    # Compares the isolation level with another.
+    # (Isolation levels providing fewer isolation are considered smaller.)
+    def <=>(other)
+      self.to_i <=> other.to_i
+    end
+
+    ReadUncommitted = new(0, :read_uncommitted, "READ UNCOMMITTED", "ReadUncommitted")
+    ReadCommitted   = new(1, :read_committed,   "READ COMMITTED",   "ReadCommitted")
+    RepeatableRead  = new(2, :repeatable_read,  "REPEATABLE READ",  "RepeatableRead")
+    Serializable    = new(3, :serializable,     "SERIALIZABLE",     "Serializable")
+
+  end  # end of class IsolationLevel
+
+
+  # Objects of this class are used to describe a reference between two tables. You can create and register them by calling BaseRecord::add_many_to_one_reference or RaseRecord::add_one_to_one_reference.
+
+  class Reference
+
+    private_class_method :new
+
+    # Returns a new reference object, describing a relation where objects of the 'source_class' refer to objects of the 'destination_class'. The 'column_info' field describes the columns used for that reference. If the 'column_info' field is a string, the primary key is used in the destination class, and the primary key prefixed by the string given in 'column_info' is used as the foreign key in the source class. If 'column_info' is an array, it contains the columns in the source class, followed by the columsn in the destination class. The field 'src_to_dst_column' contains the name of the column in the source class, which is referring to one object of the destination class. The field 'dst_to_src_column' contains the name of the column in the destination class, which is referring to one or many objects of the source class. After the reference has been created reader, loader and setter functions are added to the 'source_class' and 'destination_class', to provide access to referenced and referring objects.
+    # This method is private, use one of the child classes OneToOneReference or ManyToOneReference, which get the same arguments, to generate references of a given type.
+    def initialize(source_class, destination_class, column_info, src_to_dst_column, dst_to_src_column)
+      unless source_class.kind_of? Class and destination_class.kind_of? Class
+        raise TypeError, "Class expected"
+      end
+      @source_class      = source_class
+      @destination_class = destination_class
+      if column_info.respond_to? :to_ary
+        column_info = column_info.to_ary.flatten
+        unless column_info.length % 2 == 0
+          raise ArgumentError, "Flattened 'column_info' array contains odd number of elements."
+        end
+        @source_columns = column_info[0, column_info.length / 2].collect { |column| column.to_s.dup.freeze }
+        @destination_columns = column_info[column_info.length / 2, column_info.length / 2].collect { |column| column.to_s.dup.freeze }
+      elsif column_info.respond_to? :to_str
+        column_info = column_info.to_str
+        @source_columns = []
+        @destination_columns = []
+        destination_class.primary_columns.each do |column|
+          @source_columns << "#{column_info}#{column}".freeze
+          @destination_columns << column
+        end
+      else
+        raise ArgumentError, "Array or String expected"
+      end
+      @source_columns.freeze
+      @destination_columns.freeze
+      @src_to_dst_column = src_to_dst_column.to_s.dup.freeze
+      @dst_to_src_column = dst_to_src_column.to_s.dup.freeze
+      # Work at the source class:
+      @source_class.set_loader(@src_to_dst_column) do |source_records, arguments|
+        unless arguments.empty?
+          raise ArgumentError, "No extra arguments may be specified for outgoing reference columns."
+        end
+        destination_records = @destination_class.select_by_value_set(
+          @destination_columns,
+          source_records.collect { |source_record|
+            @source_columns.collect { |column| source_record[column] }
+          },
+          *arguments
+        )
+        destination_record_hash = {}
+        destination_records.each do |destination_record|
+          destination_record_hash[@destination_columns.collect { |column| destination_record[column] }] = destination_record
+          if self.one_to_one?
+            destination_record[@dst_to_src_column] = nil
+          end
+        end
+        source_records.each do |source_record|
+          destination_record = 
+            destination_record_hash[@source_columns.collect { |column| source_record[column] }]
+          source_record[@src_to_dst_column, *arguments] = destination_record
+          if destination_record and self.one_to_one?
+            destination_record[@dst_to_src_column] = source_record
+          end
+        end
+        next destination_records
+      end
+      @source_columns.each_index do |column_index|
+        source_column = @source_columns[column_index]
+        destination_column = @destination_columns[column_index]
+        @source_class.set_reader(source_column) do |source_record, arguments|
+          destination_record = source_record[@src_to_dst_column]
+          next destination_record ? destination_record[destination_column] : source_record[source_column]
+        end
+        @source_class.set_setter(source_column) do |source_record, value|
+          source_record.delete_from_cache(@src_to_dst_column)
+          source_record[source_column] = value
+        end
+      end
+      if self.one_to_one?
+        @source_class.set_setter(@src_to_dst_column) do |source_record, value|
+          old_destination_record = source_record[@src_to_dst_column]
+          if old_destination_record
+            old_destination_record[@dst_to_src_column] = nil
+          end
+          source_record[@src_to_dst_column] = value
+          if value
+            value[@dst_to_src_column] = source_record
+          end
+        end
+      end
+      # Work at the destination class:
+      @destination_class.set_loader(@dst_to_src_column) do |destination_records, arguments|
+        unless arguments.empty?
+          unless arguments[0].respond_to? :to_str
+            raise "First argument of reader method is not a SQL snippet string."
+          end
+          arguments[0] = arguments[0].to_str
+        end
+        source_records = @source_class.select_by_value_set(
+          @source_columns,
+          destination_records.collect { |destination_record|
+            @destination_columns.collect { |column| destination_record[column] }
+          },
+          *arguments
+        )
+        destination_record_hash = {}
+        destination_records.each do |destination_record|
+          destination_record_hash[@destination_columns.collect { |column| destination_record[column] }] = destination_record
+          destination_record[@dst_to_src_column, *arguments] =
+            if self.many_to_one?
+              FlexiRecord::RecordArray.new(@source_class)
+            else
+              nil
+            end
+        end
+        source_records.each do |source_record|
+          destination_record = destination_record_hash[@source_columns.collect { |column| source_record[column] }]
+          source_record[@src_to_dst_column] = destination_record
+          if destination_record
+            if self.many_to_one?
+              destination_record[@dst_to_src_column, *arguments] << source_record
+            else
+              destination_record[@dst_to_src_column, *arguments] = source_record
+            end
+          end
+        end
+        next source_records
+      end
+      if self.one_to_one?
+        @destination_class.set_setter(@dst_to_src_column) do |destination_record, value|
+          old_source_record = destination_record[@dst_to_src_column]
+          if old_source_record
+            old_source_record[@src_to_dst_column] = nil
+          end
+          destination_record[@dst_to_src_column] = value
+          if value
+            value[@src_to_dst_column] = destination_record
+          end
+        end
+      end
+      return self
+    end
+
+    # Combines two ManyToOneReference's to a many-to-many relation. 'other_reference' is another Reference object (as returned by Reference#new, BaseRecord#add_many_to_one_reference or BaseRecord#add_one_to_one_reference), 'own_column' is the virtual column to be installed in the destination_class of this object and 'other_column' is the virtual column to be installed in the destination_class of the 'other_reference' object.
+    def combine(other_reference, own_column, other_column)
+      unless other_reference.kind_of? FlexiRecord::Reference
+        raise TypeError, "Object of class FlexiRecord::Reference expected."
+      end
+      reference1 = self
+      reference2 = other_reference
+      column1 = own_column.to_s
+      column2 = other_column.to_s
+      unless self.source_class == other_reference.source_class
+        "Combining references having different source classes is not possible."
+      end
+      relationship_class = self.source_class
+      [
+        [reference1, reference2, column1, column2],
+        [reference2, reference1, column2, column1]
+      ].each do |source_reference, destination_reference, source_column, destination_column|
+        source_class = source_reference.destination_class
+        destination_class = destination_reference.destination_class
+        tmp1 = []
+        destination_reference.source_columns.each_index do |column_index|
+          tmp1 << [
+            destination_reference.source_columns[column_index],
+            destination_reference.destination_columns[column_index]
+          ]
+        end
+        source_class.set_loader destination_column do |source_records, arguments|
+          sql_arguments = arguments.dup
+          sql_snippet = sql_arguments.shift
+          unless sql_snippet.nil?
+            unless sql_snippet.respond_to? :to_str
+              raise "First argument of reader method is not a SQL snippet string."
+            end
+            sql_snippet = sql_snippet.to_str
+          end
+          # TODO: Do SELECT DISTINCT. (breaks for now, as ORDER BY expressions must appear in select list)
+          destination_records = unless source_records.empty?
+            destination_class.sql(
+              'SELECT ' << FlexiRecord::DefaultTableAlias << '.* FROM (' <<
+              'SELECT "obj".*, ' << relationship_class.columns.collect { |column| '"rel"."' << column << '" AS "_flexirecord_rel_' << column << '"' }.join(', ') << ' FROM ' << relationship_class.table << ' "rel" JOIN ' << destination_class.table << ' "obj" ON ' << tmp1.collect { |tmp1a, tmp1b| '"rel"."' << tmp1a << '" = "obj"."' << tmp1b << '"' }.join(' AND ') << ' WHERE (' << source_reference.source_columns.collect { |column| '"rel"."' << column << '"' }.join(', ') << ') IN (' << source_records.collect { |record| '(' << source_reference.source_columns.collect { '$' }.join(', ') << ')' }.join(', ') << ')' <<
+              ') AS ' << FlexiRecord::DefaultTableAlias << ' JOIN ' << relationship_class.table << ' ' << FlexiRecord::RelationshipTableAlias << ' ON ' << relationship_class.primary_columns.collect { |column| '' << FlexiRecord::RelationshipTableAlias << '."' << column << '" = ' << FlexiRecord::DefaultTableAlias << '."_flexirecord_rel_' << column << '"' }.join(' AND ') << ' ' << sql_snippet.to_s,
+              *(source_records.collect { |record| source_class.primary_columns.collect { |column| record.read(column) } } + sql_arguments)
+            )
+          else
+            FlexiRecord::RecordArray.new(destination_class)
+          end
+          destination_record_hash = {}
+          destination_records.each do |destination_record|
+            (destination_record_hash[
+              source_reference.source_columns.collect { |column|
+                destination_record['_flexirecord_rel_' << column]
+              }
+            ] ||= FlexiRecord::RecordArray.new(destination_class)) << destination_record
+            relationship_hash = { destination_reference.src_to_dst_column => destination_record }
+            relationship_class.columns.each do |column|
+              relationship_hash[column] =
+              destination_record.delete_from_cache("_flexirecord_rel_#{column}")
+            end
+            destination_record[FlexiRecord::RelationshipColumn] = relationship_class.new(relationship_hash)
+          end
+          source_records.each do |source_record|
+            source_record[destination_column, *arguments] = (destination_record_hash[source_reference.destination_columns.collect { |column| source_record[column] } ]) || FlexiRecord::RecordArray.new(destination_class)
+          end
+          next destination_records
+        end
+      end
+    end
+
+    # Class, whose objects are referring to others.
+    attr_reader :source_class
+
+    # Class, whose objects are referred by others.
+    attr_reader :destination_class
+
+    # Columns in the referring class, providing the foreign key.
+    attr_reader :source_columns
+
+    # Columns in the referred class, providing a unique or primary key.
+    attr_reader :destination_columns
+
+    # Name (String) of the column in the source class, which is referring to one object of the destination class.
+    attr_reader :src_to_dst_column
+
+    # Name (String) of the column in the destination class, which is referring to one or many objects of the source class.
+    attr_reader :dst_to_src_column
+
+    # Returns true, if the object describes a one-to-one relation.
+    def one_to_one?
+      @one_to_one
+    end
+
+    # Returns true, if the object describes a many-to-one relation.
+    def many_to_one?
+      not @one_to_one
+    end
+
+  end  # end of class Reference
+
+
+  # One-to-one reference. See FlexiRecord::Reference for details.
+
+  class OneToOneReference < FlexiRecord::Reference
+
+    public_class_method :new
+
+    # See FlexiRecord::Reference.new for details.
+    def initialize(*arguments)
+      super
+      @one_to_one = true
+    end
+
+  end  # end of class OneToOneReference
+
+
+  # Many-to-one reference. See FlexiRecord::Reference for details.
+
+  class ManyToOneReference < FlexiRecord::Reference
+
+    public_class_method :new
+
+    # See FlexiRecord::Reference.new for details.
+    def initialize(*arguments)
+      super
+      @one_to_one = false
+    end
+
+  end  # end of class ManyToOneReference
+
+
+  # An abstract record, super-class of all record classes. By now there is only one sub-class 'BaseRecord', which represents a record being directly stored in one database table. Other sub-classes might be added in near future, to be able to use inheritance of data models to be stored in the database using multiple tables in the backend for one model.
+
+  class AbstractRecord
+
+    private_class_method :new
+
+  end  # end of class AbstractRecord
+
+
+  # Sub-class of Array to provide special methods to be used on multiple database records at once.
+
+  class RecordArray < Array
+
+    # Creates a new Array to hold objects of type 'record_class'. Additional arguments will be passed to Array#new.
+    def initialize(record_class, *arguments)
+      super(*arguments)
+      @flexirecord_class = record_class
+      @flexirecord_preloaded = {}
+    end
+
+    # Returns the record class of the elements of the array.
+    def record_class
+      @flexirecord_class
+    end
+
+    # Preloads a virtualized column of an Array of records at once (without doing one SQL query for each record). Can return another RecordArray, which can be used for the next level of preloading.
+    def preload(column, *arguments)
+      column = column.to_s
+      @flexirecord_class.prepare_read_parameters(column, arguments)
+      cache_key = [column] + arguments
+      if @flexirecord_preloaded.has_key?(cache_key)
+        return @flexirecord_preloaded[cache_key]
+      end
+      column = column.to_s
+      loader = self.record_class.loader(column)
+      unless loader
+        raise ArgumentError, "Could not preload column '#{column}', due to missing loading procedure."
+      end
+      return @flexirecord_preloaded[cache_key] = loader.call(self, arguments)
+    end
+
+    # Returns a RecordArray of re-selected objects. This can be used to re-sort records by the database, to do further filtering, or to reload all records at once. The result will not contain duplicates, even if there are duplicates in the receiver of the method call.
+    def reselect(sql_snippet=nil, *arguments)
+      unless self.empty?
+        @flexirecord_class.select_by_value_set(@flexirecord_class.primary_columns, self.collect { |record| @flexirecord_class.primary_columns.collect { |column| record.read(column) } }, sql_snippet, *arguments)
+      end
+      return self
+    end
+
+  end  # end of class RecordArray
+
+
+  # A record representing a row of a database table or query result.
+
+  class BaseRecord < FlexiRecord::AbstractRecord
+
+    include MonitorMixin
+
+    public_class_method :new
+
+    class << self  # singleton meta class of BaseRecord
+
+      # Sets the database schema name for this class.
+      def schema_name=(schema_name)
+        @schema_name = schema_name ? schema_name.to_s.dup.freeze : nil
+      end
+
+      # Sets the database table name for this class. This must only be used on sub-classes of BaseRecord, and never on BaseRecord itself.
+      def table_name=(table_name)
+        @table_name = table_name ? table_name.to_s.dup.freeze : nil
+      end
+
+      # Returns the database schema name of this class (or of it's superclass, if it has no own schema name)
+      def schema_name
+        @schema_name or (
+          (superclass <= FlexiRecord::BaseRecord) ?
+          superclass.schema_name :
+          nil
+        )
+      end
+
+      # Returns the database schema name, even if no schema is set (in this case "public" is returned.
+      def schema_name!
+        schema_name or "public".freeze
+      end
+
+      # Returns the table name of this class (or of it's superclass, if it has no own table name)
+      def table_name
+        @table_name or (
+          (superclass <= FlexiRecord::BaseRecord) ?
+          superclass.table_name :
+          nil
+        )
+      end
+
+      # Returns the table name, or raises an error, if no name is found.
+      def table_name!
+        table_name or
+          raise "No table name set for #{self.name}."
+      end
+
+      # Returns an SQL snippet including the quoted schema and table name.
+      def table
+        schema_name ?
+          %Q("#{schema_name}"."#{table_name!}") :
+          %Q("#{table_name!}")
+      end
+
+      # Sets the connection pool to use for this class in general.
+      def connection_pool=(pool)
+        @connection_pool = pool
+      end
+
+      # Returns the connection pool being used for this class in general.
+      def connection_pool
+        @connection_pool
+      end
+
+      # Sets the ConnectionPool to use for this class in the current thread.
+      def thread_connection_pool=(pool)
+        pool_hash = Thread.current[:flexirecord_thread_connection_pools] ||= {}
+        if pool.nil?
+          pool_hash.delete(self)
+        else
+          pool_hash[self] = pool
+        end
+        nil
+      end
+
+      # Returns the ConnectionPool being used for the current thread, if an explicit pool was set for the current thread.
+      def thread_connection_pool
+        (Thread.current[:flexirecord_thread_connection_pools] ||= {})[self]
+      end
+
+      # Calls the given block with a Connection object to the database being used to store objects of this class.
+      def use_connection
+        pool = nil
+        catch :found do
+          current_class = self
+          while current_class <= FlexiRecord::BaseRecord
+            throw :found if pool = current_class.thread_connection_pool
+            current_class = current_class.superclass
+          end
+          current_class = self
+          while current_class <= FlexiRecord::BaseRecord
+            throw :found if pool = current_class.connection_pool
+            current_class = current_class.superclass
+          end
+          raise "No connection pool set for #{self.name}."
+        end
+        pool.use_connection do |connection|
+          return yield(connection)
+        end
+      end
+
+      # Returns true, if a transaction is in progress on the connection used for accessing the table of this class.
+      def transaction?
+        use_connection do |connection|
+          return connection.transaction?
+        end
+      end
+
+      # Returns the isolation_level of a transaction in progress on the connection used for accessing the table of this class.
+      def isolation_level
+        use_connection do |connection|
+          return connection.isolation_level
+        end
+      end
+
+      # Wraps the given block in a transaction of the database being used to store objects of this class. See FlexiRecord::Connection#transaction for details of the command.
+      def transaction(*arguments)
+        use_connection do |connection|
+          connection.transaction(*arguments) do
+            return yield
+          end
+        end
+        result
+      end
+
+      # Autodetects the columns (and primary key columns) of the underlaying table, to be later retrieved by the 'columns' and the 'primary_columns' methods.
+      def autodetect_columns
+        columns = []
+        primary_columns = []
+        db_query('SELECT ' <<
+            '"pg_attribute"."attname", ' <<
+            '"pg_constraint"."conkey" @> ARRAY["pg_attribute"."attnum"] AS "primary" ' <<
+            'FROM "pg_attribute" ' <<
+            'JOIN "pg_class" ON "pg_attribute"."attrelid" = "pg_class"."oid" ' <<
+            'JOIN "pg_namespace" ON "pg_class"."relnamespace" = "pg_namespace"."oid" ' <<
+            'LEFT JOIN "pg_constraint" ON "pg_class"."oid" = "pg_constraint"."conrelid" ' <<
+            'WHERE "pg_attribute"."attnum" > 0 ' <<
+            'AND "pg_class"."relname" = $ ' <<
+            'AND "pg_namespace"."nspname" = $ ' <<
+            'AND "pg_constraint"."contype" = $ ' <<
+            'ORDER BY "attnum"',
+            table_name!, schema_name!, 'p').each do |attribute_record|
+            attribute_record.attname.freeze
+          columns << attribute_record.attname
+          primary_columns << attribute_record.attname if attribute_record.primary
+        end
+        @primary_columns = primary_columns.freeze
+        @columns = columns.freeze
+        nil
+      end
+
+      # Returns an array of columns (String's) of the underlaying table. The columns may be autodetected (and cached) at the first call of this method.
+      def columns
+        return [].freeze if table_name.nil?
+        autodetect_columns if @columns.nil?
+        return @columns
+      end
+
+      # Returns an array of columns (String's) being part of the primary key of the underlaying table. (This will be in most cases an Array with one entry.) The columns may be autodetected (and cached) at the first call of this method.
+      def primary_columns
+        return [].freeze if table_name.nil?
+        autodetect_columns if @primary_columns.nil?
+        return @primary_columns
+      end
+
+      # This method is used on each Array of records being selected from the database via the 'sql' or 'select' method. It does nothing, but can be extended to automatically preload certain fields for example.
+      def after_select(records)
+      end
+
+      # Executes the given SQL query with optional arguments on the database being used to store objects of this class. Returns an array of objects of the class this method is used on (containing the data of all rows of the query result).
+      def sql(command_template, *command_arguments)
+        records = nil
+        if command_template
+          transaction(:unless_open, :serializable) do
+            use_connection do |connection|
+              records = connection.record_query(self, command_template, *command_arguments)
+            end
+            after_select(records)
+          end
+        else
+          records = FlexiRecord::RecordArray.new(self)
+          after_select(records)
+        end
+        return records
+      end
+
+      # Executes the given SQL query with optional arguments on the database being used to store objects of this class. Returns a single object of the class this method is used on (containing the data of the first row of the query result.)
+      def sql1(*arguments)
+        sql(*arguments).first
+      end
+
+      # Executes the given SQL query with optional arguments on the database being used to store objects of this class. Returns an array of BaseRecord's (but NOT sub-classes of BaseRecord) containing the data of all rows of the query result.
+      def db_query(command_template, *command_arguments)
+        use_connection do |connection|
+          return connection.query(command_template, *command_arguments)
+        end
+      end
+
+      # Executes the given SQL query with optional arguments on the database being used to store objects of this class. Returns an array of  BaseRecord's (but NOT sub-classes of BaseRecord) containing the data of the first row of the query result.
+      def db_query1(*arguments)
+        db_query(*arguments).first
+      end
+
+      # Executes the given SQL command with optional arguments on the database being used to store objects of this class. Returns nil.
+      def db_execute(command_template, *command_arguments)
+        use_connection do |connection|
+          return connection.execute(command_template, *command_arguments)
+        end
+      end
+
+      # Wrapper for the 'sql' method including already a part of the SQL select command. Please see the source code to understand how this method works. If there is a primary key, the selection will not contain duplicates, even if there have been JOINs with other tables.
+      def select(sql_snippet=nil, *arguments)
+        sql("SELECT#{(sql_snippet.nil? or self.primary_columns.empty?) ? '' : ' DISTINCT'} #{FlexiRecord::DefaultTableAlias}.* FROM #{table} #{FlexiRecord::DefaultTableAlias}#{sql_snippet ? ' ' : ''}#{sql_snippet}", *arguments)
+      end
+
+      # Same as 'select', but returns only the first member of the Array, or nil.
+      def select1(*arguments)
+        select(*arguments).first
+      end
+
+      # Executes an SQL query, selecting rows matching a given set of keys and values, optionally appending a given SQL snippet with parameters. Returns an Array of records. If there is a primary key, the selection will not contain duplicates, even if there have been JOINs with other tables.
+      def select_by_value_set(keys, set_of_values, sql_snippet=nil, *arguments)
+        flattened_values = set_of_values.to_ary.flatten
+        if flattened_values.empty?
+          return sql(nil)
+        else
+          if sql_snippet
+            return sql(
+              'SELECT ' << (self.primary_columns.empty? ? '' : 'DISTINCT ') << FlexiRecord::DefaultTableAlias << '.* FROM (' <<
+              'SELECT * FROM ' << table << ' WHERE (' << keys.collect { |key| '"' << key << '"' }.join(', ') << ') ' << 'IN (' << set_of_values.collect { |values| '(' << values.collect { |value| '$' }.join(', ') << ')' }.join(', ') << ')' <<
+              ') AS ' << FlexiRecord::DefaultTableAlias << ' ' << sql_snippet.to_s,
+              *(flattened_values + arguments)
+            )
+          else
+            return sql(
+              'SELECT' << (self.primary_columns.empty? ? '' : ' DISTINCT') << ' * FROM ' << table << ' WHERE (' << keys.collect { |key| '"' << key << '"' }.join(', ') << ') ' << 'IN (' << set_of_values.collect { |values| '(' << values.collect { |value| '$' }.join(', ') << ')' }.join(', ') << ')',
+              *(flattened_values + arguments)
+            )
+          end
+        end
+      end
+
+      # Adds a "shortcut" for a parameter to reader and loader functions.
+      #
+      # Example: List.add_read_option :items, :by_name, 'ORDER BY "name"'
+      def add_read_option(column, symbol, value)
+        unless symbol.kind_of? Symbol
+          raise "Symbol expected as second argument to 'add_read_option'."
+        end
+        (@read_options ||= {})[[column.to_s, symbol]] = value
+      end
+
+      # Returns the value of a "shortcut" for a parameter to reader and loader functions.
+      def read_option_value(column, symbol)
+        value = (@read_options || {})[[column.to_s, symbol]] || ((superclass <= FlexiRecord::BaseRecord) ? superclass.read_option_value(column, symbol) : nil)
+      end
+
+      # Modifies a parameter array by replacing "shortcut" symbols being defined by add_read_option. Returns the parameter array.
+      def prepare_read_parameters(column, parameters)
+        option = parameters.first
+        value = read_option_value(column, option.nil? ? :default : option)
+        if value
+          parameters[0] = value
+        elsif option == :default
+          parameters.shift
+        end
+        return parameters
+      end
+
+      # Sets a given block to be the "reader function" for a particlular virtualized column. A reader function is invoked, when you try to read a value of the given 'column' of a record. Two arguments are passed to the block. The first is the record, whose data is to be read, the second is an Array of arguments passed to the method used for reading the value. The block has to evaluate to the value which should be read.
+      def set_reader(column, &reader)
+        (@readers ||= {})[column.to_s] = reader
+      end
+
+      # Returns the reader function (a Proc object) for a certain virtualized column.
+      def reader(column)
+        (@readers || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.reader(column) : nil)
+      end
+
+      # Returns an array containing all virtualized columns having a reader Proc stored in the class.
+      def reader_columns
+        (@readers || {}).keys + (
+          (superclass <= FlexiRecord::BaseRecord) ?
+          superclass.reader_columns :
+          []
+        )
+      end
+
+      # Sets a given block to be the "loader function" for a particular virtualized column. Loader functions are invoked, when you try to read an uncached value of the given 'column' of a record, or when you preload data for a whole Array of records. Two arguments are passed to the block. The first is an Array of records, whose data is to be loaded, the second is an Array of arguments passed to the method used for accessing the value. The block has to evaluate to an Array of records, which can be used for more than one level deep preloads.
+      def set_loader(column, &loader)
+        (@loaders ||= {})[column.to_s] = loader
+      end
+
+      # Returns the loader function (a Proc object) for a certain virtualized column.
+      def loader(column)
+        (@loaders || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.loader(column) : nil)
+      end
+
+      # Sets a given block to be the "setter function" for a particular virtualized column. The setter function is invoked, when you set the value of the given 'column' of a record. Two arguments are passed to the block. The first is the record, whose data is to be changed, the second is the new value to be written into the 'column' field.
+      def set_setter(column, &setter)
+        (@setters ||= {})[column.to_s] = setter
+      end
+
+      # Returns the setter function (a Proc object) for a certain virtualized column.
+      def setter(column)
+        (@setters || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.setter(column) : nil)
+      end
+
+      # Adds an OneToOneReference to the class (by simply creating it). The first argument is the destination class, followed by arguments being passed to Reference.new.
+      def add_one_to_one_reference(destination_class, *arguments)
+        return FlexiRecord::OneToOneReference.new(
+          self, destination_class, *arguments
+        )
+      end
+
+      # Adds a ManyToManyReference to the class (by simply creating it). The first argument is the destination class, followed by arguments being passed to Reference.new.
+      def add_many_to_one_reference(destination_class, *arguments)
+        return FlexiRecord::ManyToOneReference.new(
+          self, destination_class, *arguments
+        )
+      end
+
+    end  # end of singleton meta class of BaseRecord
+
+    private  # methods of BaseRecord
+
+      # Saves a copy of the values of the primary key in the @old_primary_key Array.
+      def copy_primary_key
+        synchronize do
+          @old_primary_key.clear
+          self.class.primary_columns.each do |column|
+            @old_primary_key[column] = self.read(column)
+          end
+        end
+        nil
+      end
+
+      # Creates a new record object with the given keys and values in the 'data' hash. If 'saved' is true, it is considered to be existent in the database already, if 'saved' is false (default), it is considered to be a new object, which has not been saved.
+      def initialize(data={}, saved=false)
+        super()
+        @data_hash = {}
+        self.update(data)
+        @saved = saved ? true : false
+        @old_primary_key = {}
+        copy_primary_key if @saved and self.class.table_name
+        nil
+      end
+
+    protected  # methods of BaseRecord
+
+      # Helper method for dup and replace. Do not use directly.
+      def dup_internal_state
+        @data_hash = @data_hash.dup
+        @old_primary_key = @old_primary_key.dup
+        nil
+      end
+
+      # Helper mthod for dup and replace. Do not use directly.
+      def read_internal_state
+        return @data_hash.dup, @saved, @old_primary_key.dup
+      end
+
+    public  # methods of BaseRecord
+
+      # Rewrites several attributes given by the keys and values in the 'data' hash. Returns self.
+      def update(data)
+        synchronize do
+          data.each { |key, value| self.set(key, value) }
+          return self
+        end
+      end
+
+      # Duplicates a record, including it's internal state.
+      def dup
+        synchronize do
+          duplicate = super
+          duplicate.dup_internal_state
+          return duplicate
+        end
+      end
+
+      # Replaces the internal state with the state of a backup. This method is needed for transaction rollbacks.
+      def replace(backup)
+        synchronize do
+          raise TypeError, "Can not restore backup of objects of other classes." unless backup.class == self.class
+          @data_hash, @saved, @old_primary_key = backup.read_internal_state
+          return self
+        end
+      end
+
+      # Reads a value (whose key can consist of multiple fields) from the internal cache. The first argument is by convention a name of a column as String(!), but NOT as a Symbol.
+      def [](*key)
+        synchronize do
+          return @data_hash[key]
+        end
+      end
+
+      # Writes a value to the internal cache. The first argument is by convention a name of a column as String(!), but NOT as a Symbol.
+      def []=(*arguments)
+        synchronize do
+          value = arguments.pop
+          key   = arguments
+          return @data_hash[key] = value
+        end
+      end
+
+      # Returns true, if the internal cache has stored the specified entry, otherwise false.
+      def has_key?(*key)
+        synchronize do
+          return @data_hash.has_key?(key)
+        end
+      end
+
+      # Deletes an entry from the internal cache, and returns it's value.
+      def delete_from_cache(*key)
+        synchronize do
+          return @data_hash.delete(key)
+        end
+      end
+
+      # Reads the field with the specified 'column'. If there is a dynamic reader, this reader is used, otherwise an existent assigned loader function is invoked or the internal cache will give a result. If there is no data for the column with the given name, then nil will be returned.
+      def read(column, *arguments)
+        column = column.to_s
+        self.class.prepare_read_parameters(column, arguments)
+        data_hash_key = [column] + arguments
+        reader = self.class.reader(column)
+        loader = self.class.loader(column)
+        synchronize do
+          if reader
+            return reader.call(self, arguments)
+          elsif @data_hash.has_key?(data_hash_key)
+            return @data_hash[data_hash_key]
+          elsif loader
+            loader.call(FlexiRecord::RecordArray.new(self.class, [self]), arguments)
+            unless @data_hash.has_key?(data_hash_key)
+              raise "Record loader failed."
+            end
+          end
+          return @data_hash[data_hash_key]
+        end
+      end
+
+      # Sets a value of a field of the specified 'column'. If there is a dynamic setter, this setter is used, otherwise the value get's written in the internal cache.
+      def set(column, value)
+        column = column.to_s
+        setter = self.class.setter(column)
+        if setter
+          setter.call(self, value)
+          return @data_hash[[column]]
+        else
+          return @data_hash[[column]] = value
+        end
+      end
+
+      # Returns an array of strings of the columns in the backend database, which have either values in the internal cache, or which have a dynamic reader function.
+      def used_columns
+        synchronize do
+          return self.class.columns & (self.class.reader_columns + @data_hash.keys.reject { |key| key.length > 1 }.collect { |key| key.first })
+        end
+      end
+
+      # Returns a string representation of the record for debugging purposes.
+      def inspect
+        synchronize do
+          processed_objects = Thread.current[:flexirecord_baserecord_inspect_cycle_check] ||= {}
+          if processed_objects[self]
+            return "#<#{self.class}:0x#{sprintf "%08x", object_id}"
+          else
+            begin
+              processed_objects[self] = true
+              return "#<#{self.class}:0x#{sprintf "%08x", object_id} #{@saved ? 'saved' : 'unsaved'}, old_primary_key = {" <<
+                self.class.primary_columns.dup.delete_if { |column| not @old_primary_key.has_key?(column) }.
+                collect { |column| column.inspect << '=>' << @old_primary_key[column].inspect }.join(', ') << "}, data = {" <<
+                self.class.columns.dup.delete_if { |column| not (@data_hash.has_key?([column]) or self.class.reader(column)) }.
+                collect { |column| column.inspect << '=>' << read(column).inspect }.join(', ') << "}>"
+            ensure
+              processed_objects.delete(self)
+            end
+          end
+        end
+      end
+
+      # Alias for the inspect method.
+      def to_s
+        inspect
+      end
+
+      undef_method :id
+      # Provides easy access to the fields of the record.
+      def method_missing(method_symbol, *arguments)
+        synchronize do
+          column = method_symbol.to_s
+          if column[-1, 1] == '='
+            column = column[0, column.length-1]
+            mode = :write
+            value = arguments.pop
+          else
+            mode = :read
+          end
+          reader                = self.class.reader(column)
+          loader                = self.class.loader(column)
+          table_column_existent = self.class.columns.include?(column)
+          if mode == :write
+            data_hash_key         = [column] + arguments
+            setter = self.class.setter(column)
+            if setter
+              setter.call(self, value)
+              return nil
+            elsif @data_hash.has_key?(data_hash_key) or reader or loader or table_column_existent
+              @data_hash[data_hash_key] = value
+              return nil
+            end
+          elsif mode == :read
+            self.class.prepare_read_parameters(column, arguments)
+            data_hash_key = [column] + arguments
+            if reader
+              return reader.call(self, arguments)
+            elsif @data_hash.has_key?(data_hash_key)
+              return @data_hash[data_hash_key]
+            elsif loader
+              loader.call(FlexiRecord::RecordArray.new(self.class, [self]), arguments)
+              unless @data_hash.has_key?(data_hash_key)
+                puts data_hash_key.inspect
+                raise "Record loader failed."
+              end
+              return @data_hash[data_hash_key]
+            elsif table_column_existent
+              unless arguments.empty?
+                raise ArgumentError, "Attribute getter method does not support arguments."
+              end
+              return nil
+            end
+          end
+          return super
+        end
+      end
+
+      # Returns true, if the record has been saved in database once, otherwise false.
+      def saved?
+        synchronize do
+          @saved
+        end
+      end
+
+      # Saves the record in the database, either by INSERT'ing or UPDATE'ing it.
+      def save
+        synchronize do
+          used_columns = self.used_columns
+          primary_key = nil
+          if @saved
+            if self.class.primary_columns.empty?
+              raise "Can not re-save a record of a table without a primary key."
+            end
+            primary_key = self.class.db_query1(
+              'UPDATE ' << self.class.table <<
+              ' SET ' << (used_columns.collect { |column| '"' << column << '" = $' }.join(', ')) <<
+              ' WHERE ' << (self.class.primary_columns.collect { |column| '"' << column << '" = $' }.join(' AND ')) <<
+              ' RETURNING ' << (self.class.primary_columns.collect { |column| '"' << column << '"' }.join(', ')),
+              *(
+                used_columns.collect { |column| read(column) } +
+                self.class.primary_columns.collect { |column| @old_primary_key[column] }
+              )
+            )
+          else
+            if used_columns.empty?
+              primary_key = self.class.db_query1('INSERT INTO ' << self.class.table << ' DEFAULT VALUES' <<
+              (self.class.primary_columns.empty? ? '' : (
+                ' RETURNING ' << (self.class.primary_columns.collect { |column| '"' << column << '"' }.join(', '))
+              )))
+            else
+              primary_key = self.class.db_query1(
+                'INSERT INTO ' << self.class.table <<
+                ' (' << (used_columns.collect { |column| '"' << column << '"' }.join(', ')) << ')' <<
+                ' VALUES (' << (used_columns.collect { |column| '$' }.join(', ')) << ')' <<
+                (self.class.primary_columns.empty? ? '' : (
+                  ' RETURNING ' << (self.class.primary_columns.collect { |column| '"' << column << '"' }.join(', '))
+                )),
+                *(
+                  used_columns.collect { |column| read(column) }
+                )
+              )
+            end
+            @saved = true
+          end
+          unless primary_key.nil?
+            self.class.primary_columns.each do |column|
+              self.set(column, primary_key.read(column))
+            end
+          end
+          copy_primary_key
+          return self
+        end
+      end
+
+      def destroy
+        if self.saved?
+          self.class.db_execute('DELETE FROM ' << self.class.table <<
+            ' WHERE ' << (self.class.primary_columns.collect { |column| '"' << column << '" = $' }.join(' AND ')),
+            *( self.class.primary_columns.collect { |column| @old_primary_key[column] } )
+          )
+          @saved = false
+        end
+        return self
+      end
+
+      # Reloads the record from the database. It can not be used on records, which have not been saved to the database yet.
+      def reload
+        synchronize do
+          if self.class.primary_columns.empty?
+            raise "Can not reload a record, which has no primary key."
+          end
+          unless self.saved?
+            raise "Can not reload a record, which has not been saved yet."
+          end
+          reloaded_record = self.class.db_query1(
+            'SELECT * FROM ' << self.class.table <<
+            'WHERE ' << (self.class.primary_columns.collect { |column| '"' << column << '" = $' }.join(' AND ')),
+            *(
+              self.class.primary_columns.collect { |column| @old_primary_key[column] }
+            )
+          )
+          if reloaded_record.nil?
+            raise DatabaseError, "Could not reload data."
+          end
+          new_data_hash = {}
+          self.class.columns.each { |column| new_data_hash[[column]] = reloaded_record.read(column) }
+          @data_hash = new_data_hash
+          return self
+        end
+      end
+
+    public  # end of methods of BaseRecord
+
+  end  # end of class BaseRecord
+
+
+  # A record representing a row of a database table which is used for cross (many-to-many) relations.
+
+  class Relationship < FlexiRecord::BaseRecord
+
+    def initialize(*arguments)
+      super
+      self['void'] = nil
+    end
+
+    # Alias for the (field) method 'void'. True, if the Relationship is void, and is to be removed, when calling 'save'.
+    def void?
+      self.void
+    end
+
+    # Instead of UPDATEing or INSERTing a value, depending on the state of the object, it is always replaced in the database. When the special attribute 'void' is set, the record will be destroyed instead of saved.
+    def save
+      # TODO: improve efficiency, when a "REPLACE" command is available in PostgreSQL
+      self.class.transaction(self, :read_committed) do
+        self.class.db_execute "LOCK TABLE #{self.class.table} IN SHARE ROW EXCLUSIVE MODE"
+        @saved =
+          self.class.select_by_value_set(self.class.primary_columns, [self.class.primary_columns.collect { |column| self.read(column) }]).length > 0
+        copy_primary_key
+        if self.void
+          return destroy
+        else
+          return super
+        end
+      end
+    end
+
+  end  # end of class Relationship
+
+
+  # A Connection object represents a distinct connection to the database.
+
+  class Connection
+
+    include MonitorMixin
+
+    # Generates a new Connection object. The passed 'options' are a hash, which may contain the following keys:
+    # - :engine (only :postgresql is supported)
+    # - :host
+    # - :port
+    # - :options
+    # - :db
+    # - :user
+    # - :pass
+    # - :data_types (used for the PostgreSQL interface to supply a mapping between OID's and ruby types, will be set automatically in the hash object, if it is nil or missing)
+    def initialize(options)
+      super()
+      options.each do |key, value|
+        case key
+        when :engine
+          @engine = value.to_sym
+        when :host
+          @host = value.to_s.dup.freeze if value
+        when :port
+          @port = value.to_i
+        when :options
+          @options = options.to_s.dup.freeze if value
+        when :db
+          @dbname = value.to_s.dup.freeze if value
+        when :user
+          @login = value.to_s.dup.freeze if value
+        when :pass
+          @passwd = value.to_s.dup.freeze if value
+        when :data_types
+          @data_types = value.to_hash.dup.freeze if value
+        else
+          raise ArgumentError, "Unknown option '#{key}'."
+        end
+      end
+      raise ArgumentError, "No engine selected." if @engine.nil?
+      raise ArgumentError, "Engine '#{@engine}' not supported." unless @engine == :postgresql
+      unless @data_types
+        @data_types = {}
+        options[:data_types] = {}
+        connection = nil
+        begin
+          connection = FlexiRecord::Connection.new(options)
+          connection.query('SELECT "oid", "typname" FROM "pg_type" WHERE typtype=$', 'b').each do |type_record|
+          @data_types[type_record.oid.to_i] = type_record.typname.to_s.freeze
+          end
+        ensure
+          connection.close if connection
+        end
+        options[:data_types] = @data_types.freeze
+      end
+      @backend_connection = PGconn.new(@host, @port, @options, nil, @dbname, @login, @passwd)
+      @transaction_stacklevel = 0
+      @isolation_level = nil
+      nil
+    end
+
+    # Executes an SQL query and returns an Array of objects of 'record_class' (which should be a sub-class of BaseRecord). The 'command_template' is an SQL statement with '$' placeholders to be replaced by the following 'command_arguments'.
+    def record_query(record_class, command_template, *command_arguments)
+      command = command_template.to_s.gsub(/\$([^0-9]|$)/) {
+        if command_arguments.empty?
+          raise ArgumentError, "Too few arguments supplied for SQL command."
+        end
+        command_argument = command_arguments.shift
+        if command_argument.kind_of? Rational
+          command_argument = command_argument.to_f
+        end
+        PGconn.quote(command_argument) << $1
+        # argument = command_arguments.shift
+        # if argument.kind_of? FlexiRecord::SqlSnippet
+        #   argument.to_s + $1
+        # else
+        #   PGconn.quote(argument) << $1
+        # end
+      }
+      raise ArgumentError, "Too many arguments supplied for SQL command." unless command_arguments.empty?
+      if $flexirecord_debug_output
+        $flexirecord_debug_output << "===>  #{command}\n"
+      end
+      begin
+        synchronize do
+          if record_class
+            backend_result = @backend_connection.async_exec(command)
+            result = FlexiRecord::RecordArray.new(record_class)
+            for row in 0...(backend_result.num_tuples)
+              record_data = {}
+              for col in 0...(backend_result.num_fields)
+                value_string = backend_result.getvalue(row, col)
+                record_data[backend_result.fieldname(col)] = if value_string.nil?
+                  nil
+                else
+                  if @data_types
+                    case @data_types[backend_result.type(col)]
+                    when "bool"    then value_string[0, 1] == 't'
+                    when "int2"    then value_string.to_i
+                    when "int4"    then value_string.to_i
+                    when "int8"    then value_string.to_i
+                    when "text"    then value_string
+                    when "varchar" then value_string
+                    when "numeric" then
+                      unless value_string =~ /^([0-9]*)(\.([0-9]+)?)?$/
+                        raise "Unexpected format for numeric data from database."
+                      end
+                      if $3
+                        $1.to_i + Rational($3.to_i, 10**($3.length))
+                      else
+                        $1.to_i
+                      end
+                    else
+                      value_string
+                    end
+                  else
+                    value_string
+                  end
+                end
+              end
+              result << record_class.new(record_data, true)
+            end
+            return result
+          else
+            @backend_connection.async_exec(command)
+            return nil
+          end
+        end
+      rescue PGError
+        raise FlexiRecord::DatabaseError, $!.message
+      end
+    end
+
+    # Same as record_query, but using BaseRecord's as 'record_class'.
+    def query(command_template, *command_arguments)
+      record_query(FlexiRecord::BaseRecord, command_template, *command_arguments)
+    end
+
+    # Same as record_query, but having no 'record_class', theirfor returning nil.
+    def execute(command_template, *command_arguments)
+      record_query(nil, command_template, *command_arguments)
+    end
+
+    # Returns true, if a transaction is in progress on this connection.
+    def transaction?
+      synchronize do
+        @transaction_stacklevel > 0
+      end
+    end
+
+    # Returns the isolation_level of a transaction in progress on this connection.
+    def isolation_level
+      synchronize do
+        @isolation_level
+      end
+    end
+
+    # Starts a transaction or "nested transaction" (implemented by using save points), if already one is in progress. The arguments to this function can be an IsolationLevel constant, a symbol representing an IsolationLevel, the special symbol :unless_open or any number of BaseRecord objects, which are copied with BaseRecord#dup and restored with BaseRecord#replace, in case the transaction fails. If :unless_open is specified, and a transaction is already open, this method does nothing, except calling the given block. As partitial rollbacks on errors won't happen in this case, it's not recommended to use the :unless_open parameter, unless you know what you are doing. IsolationLevel's are only regarded, if there is no transaction open yet.
+    def transaction(*arguments)
+      isolation_level = nil
+      records = []
+      unless_open_mode = false
+      arguments.flatten.each do |argument|
+        if argument.kind_of? FlexiRecord::IsolationLevel
+          isolation_level_argument = argument
+        elsif argument.respond_to? :to_sym
+          isolation_level_argument = FlexiRecord::IsolationLevel.by_symbol(argument)
+        end
+        if argument.nil?
+          # nothing
+        elsif argument == :unless_open
+          unless_open_mode = true
+        elsif isolation_level_argument
+          unless isolation_level.nil?
+            raise ArgumentError, "Multiple isolation levels given."
+          end
+          isolation_level = isolation_level_argument
+        elsif argument.kind_of? Symbol
+          raise ArgumentError, "Unknown symbol #{argument.inspect} given as argument to transaction method."
+        else
+          records << argument
+        end
+      end
+      if unless_open_mode and not records.empty?
+        raise ArgumentError, "No records may be specified, if a transaction is started 'unless_open'."
+      end
+      synchronize do
+        if unless_open_mode and transaction?
+          return yield
+        end
+        backup = records.collect { |record| record.dup }
+        old_stacklevel = @transaction_stacklevel
+        success = true
+        begin
+          if @transaction_stacklevel == 0
+            @isolation_level = isolation_level
+            if isolation_level
+              execute("BEGIN TRANSACTION ISOLATION LEVEL #{isolation_level}")
+            else
+              execute('BEGIN TRANSACTION')
+            end
+          else
+            execute('SAVEPOINT "FlexiRecord_' << @transaction_stacklevel.to_s << '"')
+          end
+          @transaction_stacklevel += 1
+          return yield
+        rescue StandardError
+          success = false
+          raise $!
+        ensure
+          @transaction_stacklevel = old_stacklevel
+          if success
+            if old_stacklevel == 0
+              execute('COMMIT TRANSACTION')
+            else
+              execute('RELEASE SAVEPOINT "FlexiRecord_' << @transaction_stacklevel.to_s << '"')
+            end
+          else
+            if old_stacklevel == 0
+              @isolation_level = 0
+              execute('ROLLBACK TRANSACTION')
+            else
+              execute('ROLLBACK TO SAVEPOINT "FlexiRecord_' << @transaction_stacklevel.to_s << '"')
+              execute('RELEASE SAVEPOINT "FlexiRecord_' << @transaction_stacklevel.to_s << '"')
+            end
+            backup.each_index do |record_index|
+              records[record_index].replace(backup[record_index])
+            end
+          end
+        end
+      end
+    end
+
+    # Closes a transaction, which can't not be used anymore.
+    def close
+      @backend_connection.close
+      @backend_connection = nil
+      nil
+    end
+
+  end  # end of class Connection
+
+
+  # A pool of database connections to be used exclusively by one thread at a time.
+
+  class ConnectionPool < ThreadResourcePool
+
+    # Creates a new ConnectionPool which automatically generates and caches Connection objects with the given options.
+    def initialize(connection_options)
+      @connection_options = connection_options.dup
+      pool_size = @connection_options.delete(:pool_size)
+      super(pool_size || 10)
+    end
+
+    # Implementation of ThreadResourcePool#generate_resource.
+    def generate_resource
+      FlexiRecord::Connection.new(@connection_options)
+    end
+
+    # Implementation of ThreadResourcePool#reset_resource.
+    def reset_resource(connection)
+      true
+    end
+
+    # Implementation of ThreadResourcePool#destroy_resource.
+    def destroy_resource(connection)
+      connection.close
+    end
+
+    # Passes a Connection object to the given block, which then can be used by the current thread.
+
+    def use_connection(*args, &block)
+      use_resource(*args, &block)
+    end
+
+    # Wrapper for Connection#transaction for the Connection of the current thread.
+    def transaction(*arguments)
+      use_connection do |connection|
+        connection.transaction(*arguments) do
+          return yield
+        end
+      end
+    end
+
+  end  # end of class ConnectionPool
+
+
+  # MixIn for BaseRecord's (or objects of sub-classes) which are sorted by a 'position' field.
+
+  module ListRecord
+
+    def save
+      self.class.transaction(self, :read_committed) do
+        self.class.db_execute "LOCK TABLE #{self.class.table} IN SHARE ROW EXCLUSIVE MODE"
+        if self.position == :first
+          db_result = self.class.db_query1(
+            'SELECT COALESCE("position" - 1, 0) AS "result" ' <<
+            'FROM ' << self.class.table << ' WHERE "position" NOTNULL ORDER BY "position" ASC)')
+        elsif self.position == :last
+          db_result = self.class.db_query1(
+            'SELECT COALESCE("position" + 1, 0) AS "result" ' <<
+            'FROM ' << self.class.table << ' WHERE "position" NOTNULL ORDER BY "position" DESC')
+        end
+        if db_result
+          self.position = db_result.result
+        else
+          self.position = 0
+        end
+        return super
+      end
+    end
+
+  end  # end of mix-in ListRecord
+
+
+end  # end of module FlexiRecord
+