Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Universal database connection API for use with Arel (minus active record)

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rspec
Octocat-spinner-32 Gemfile
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 arc.gemspec
README.md

Arc (**Ar**el **C**onnection)

Arc is a database connection engine that provides everything Arel needs to construct an AST. You can use sqlite, postgresql and/or mysql.

Arc gives you:

  • quoting and casting of values as they enter and exit the data store
  • standard and thread safe CRUD interface for executing queries
  • a hash-like interface that provides information about the tables and columns in your database (see below)

There are two dependencies: q and arel itself.

Arc lets you use arel without the cost of including active record as a dependency.

Arel is a very capable and inspired bit of code which provides machinery for building an abstract syntax tree(ast) of a complex sql query in pure ruby.

Arc is not:

Arc isn't an ORM. There has been some recent discussion about the state of ruby ORMs. Arc does not make any attempt to pass judgement against any of the fine ORMs out there. Arc came out of a need for a lighter weight method for manipulating data in a database. Arc gives developers flexibility to build their own frameworks and write smaller libraries with fewer dependencies.

Installation

Add this to your Gemfile

gem 'pg' #'mysql2' or 'sqlite'
gem 'arc'

Basics

Connect to a database:

require 'arc'
@store = Arc::DataStores[:postgres].new({
  database: arc_development,
  host: localhost,
  user: superman
})
@store[:superheros]
# => <Arc::DataStores::ObjectDefinitions::SqliteTable:0x007f86d4026f68 @name="superheros">
@store[:superheros].column_names
# => [:is_awesome, :name, :id ]
@store[:superheros][:id]
# => #<Arc::DataStores::ObjectDefinitions::SqliteColumn @name='id'>
@store[:superheros][:id].primary_key?
# => true
@store[:superheros][:is_awesome].type
# => :bool

Execute a query

Build an Arel query and pass it to one of the store's CRUD methods:

"Read" Example:

s = Arel::Table.new :superheros
s.project(s[:name], s[:id], s[:is_awesome])
@store.read s
# => [{ :id => 1, :name => 'superman', :is_awesome => true  }
# =>  { :id => 2, :name => 'batman',   :is_awesome => false }
# =>  { :id => 3, :name => 'ironman',  :is_awesome => nil   }]

"Create" example

im = Arel::InsertManager.new
im.insert([
  [superheros[:name], 'green hornet'],
  [superheros[:is_awesome], true]
])
@store.create im
# => { :id => 4, :name => 'green hornet', :is_awesome => true }

Advanced

Arc handles some of the more complex features of arel, like complex joins:

s = Arel::Table.new :superheros
sp = Arel::Table.new :superheros_powers
p = Arel::Table.new :powers
stmt = s.join(sp).on(s[:id].eq(sp[:superhero_id]))
 .join(p).on(p[:id].eq(sp[:power_id]))
 .project(
   s[:name].as('superhero_name'),
   p[:name].as('power_name')
 )
@store.read stmt
# => [{:superhero_name => 'superman', :power_name => 'flight'},
# =>  {:superhero_name => 'superman', :power_name => 'x-ray-vision'},
# =>  {:superhero_name => 'batman', :power_name => "a belt'}]

TODO

Arc is a new library. The test suite has excellent coverage, but bugs need to be identified, tested and fixed. Next step is to add RDoc magic. A long term goal would be to add on to the schema interface to allow for some ddl operations.

Development

Install dependencies with bundler Make sure you have bundler installed, point your terminal to the project's root directory and run

$ bundle install

Running the tests:

$ rake test

To run the tests agains a particular adapter

$ rake test:adapter[<your-adapter-here>]
Something went wrong with that request. Please try again.