Speaky CSV

CSV imports and exports for ActiveRecord.

For example

Lets say there exists a User class:

# in app/models/user.rb
class User < ActiveRecord::Base
  ...
end

Speaky can be used to import and export user records. The definition of the csv format could look like this:

# in app/csv/user_csv.rb
class UserCsv < SpeakyCsv::Base
  define_csv_fields do |config|
    config.field :id, :email, :roles
  end
end

Now lets import some user records. An import csv will always have an initial header row, with each following row representing a user record. lets import the following csv file (whitespace for clarity):

# my_import.csv
id, email,              roles
22, admin@example.test, admin
  , newbie@user.test,   user

This file can be imported like this:

File.open "my_import.csv", "r" do |io|
  importer = UserCsv.new.active_record_importer io, User
  importer.each { |user| user.save }
end

Custom CSV formats

Speaky

Speaky allows customization of csv files to a degree, but some conventions need to be followed.

At a high level, the csv ends up looking similar to the way active record data gets serialized into form parameters which will be familiar to many rails developers. The advantage of this approach is that associated records be imported and exported.

Installation

Add this line to your application's Gemfile:

gem 'speaky_csv'

And then execute:

$ bundle

Or install it yourself as:

$ gem install speaky_csv

Usage

Subclass SpeakyCsv::Base and define a csv format for an active record class. For example:

# in app/csv/user_csv.rb
class UserCsv < SpeakyCsv::Base
  define_csv_fields do |config|
    config.field :id, :first_name, :last_name, :email

    config.has_many :roles do |r|
      r.field :role_name
    end
  end
end

See the rdoc for more details on how to configure the format.

Once the format is defined records can be exported like this:

$ exporter = UserCsv.new.exporter(User.all)
$ File.open('users.csv', 'w') { |io| exporter.each { |row| io.write row } }

TODO:

describe importing to attribute list
describe importing to to active records
describe how to transform with an enumerator

Recommendations

Add id and _destroy fields for active record models
For associations, use nested_attributes_for and add id and _destroy fields
Use optimistic locking and add lock_version to csv

TODO

[x] export only fields
[x] configurable id field (key off an external_id for example)
[x] export validations
[x] attr import validations
[x] active record import validations
[ ] has_one associations
[ ] required fields (make lock_version required for example)
[ ] transformations for values via accessors on class
[ ] public stable api for csv format definition
[ ] assign attrs one at a time so they don't all fail together

Contributing

Fork it ( http://github.com/ajh/speaky_csv/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request