== Abstract ==

ActiveRelation is a Relational Algebra for Ruby. It simplifies the generation of both the simplest and the most complex of SQL queries and it transparently adapts to various RDBMS systems. It is intended to be a framework framework; that is, you can build your own ORM with it, focusing on innovative object and collection modeling as opposed to database compatibility and query generation.

== A Gentle Introduction ==

Generating a query with ARel is simple. For example, in order to produce

    SELECT * FROM users
   
you construct a table relation and convert it to sql:

    ActiveRelation::Table.new(:users).to_sql
   
In fact, you will probably never call `#to_sql` directly. Let `users = ActiveRelation::Table.new(:users)`. You can iterate through all rows in the `users` table like this:

    users.each { |user| ... }
    
In other words, Arel relations behave similar regular Ruby collections. Let's have a look at a concrete example:

    users.first # => {'id' => 10, 'name' => 'bob'}
    
As you can see, Arel converts the rows into a hash, the values of which are the appropriate Ruby primitive (integers, strings, and so forth).

== Relational Algebra ==

Arel is based on the Relational Algebra, a mathematical model that is also the inspiration for relational databases. ActiveRelation::Relation objects do not represent queries per se (i.e., they are not object-representations of `SELECT`, `INSERT`, `UPDATE`, or `DELETE`), rather they represent a collection of data that you can select from, insert into, update, and delete.For example, to insert a row into the users table, do the following:

    users.insert({'id' => 11, 'name' => 'amy'})
    
To delete all users:

    users.delete
    
To update:

    users.update({'name' => 'carl'})
    
As you can see, the `relation` users does not represent an individual query; rather it is an abstraction on a collection of data and it can produce appropriate queries to do the various CRUD operations.

=== More Sophisticated Queries ===

Following the Relational Algebra, Arel's interface uses some jargon that differs from standard SQL. For example, in order to add a `WHERE` clause to your relations, you use the `select` operation:

    users.select(users[:name].equals('amy')) # => SELECT * FROM users WHERE users.name = 'amy'

What would, in SQL, be part of the `SELECT` clause is called here a `projection`:

    users.project(users[:id]) # => SELECT users.id FROM users

The best property of the Relational is compositionality, or closure under all operations. For example, to combine the two previous queries:

    users                                 \
      .select(users[:name].equals('amy')) \
      .project(users[:id])
    # => SELECT users.id FROM users WHERE users.name = 'amy'

== Contributions ==

I appreciate all contributions to ActiveRelation. There is only one "unusual" requirement I have concerning code style: all specs should be written without mocks, using concrete examples to elicit testable behavior. This has two benefits: it 1) ensures the tests serve as concrete documentation and 2) suits the functional nature of this library, which emphasizes algebraic transformation rather than decoupled components.