CSV Records

This Rails plugin extends ActiveRecord::Base for simple loading and dumping of CSV files.

Installation

You must specify the base CSV_DIR pathname, either in application.rb, your environment file, or directly in your ActiveRecord::Base instance.

Rails 3:

rails plugin install git://github.com/wtn/csv_records.git

Rails 2:

script/plugin install git://github.com/wtn/csv_records.git

Public Methods

The csv_exportable module provides the csv_write method, which writes each row in the table to disk. You may specify which columns and rows to export by passing options to the method or overriding defaults with methods in your class. Exporting is quick, as records are loaded as arrays of arrays with ActiveRecord::Base.select_rows, rather than being instantiated as normal ActiveRecord objects. You may use the default scopes and file options or you may pass custom parameters. This method returns the number of rows in the export scope.

The csv_importable module provides the csv_import method, which saves each CSV row as an ActiveRecord object. Callbacks are executed as normal. Each row is loaded with create! inside one transaction for the whole data set. If any row fails, the whole data import will be rolled back. This method returns the number of rows added during the import.

The table_empty module adds table_empty?, which is helpful if you need to check if you've imported data yet (or if any data exists to export). The method returns nil if the klass' table does not exist, true or false otherwise.

Private Methods

csv_export_column_names may be used with csv_export_excluded_column_names, noncontent_column_names, timestamp_column_names, super(), or other methods you write to control which columns are included when exporting data. The simplest way is to override csv_export_excluded_column_names in your class--it returns an empty array by default.

csv_filepath, csv_dir and csv_filename determine filepath generation. csv_dir depends on the CSV_DIR constant, which may be set in your class or globally in your environment file. Alternately, you may pass the :filepath option and avoid using these methods altogether.

Examples

Person.csv_import # create active_record rows from people.csv

Person.csv_import(*%w{managers players})

load from managers.csv and players.csv

Stadium.csv_write # dump all rows into stadiums.csv

Bird.table_empty? # check if birds exist (nil if table missing)

zebra_scope = Zebra.where('age > 7') Zebra.csv_write(:scope => zebra_scope) # pass a custom scope zebra_scope.base_class.write_csv(:scope => zebra_scope) # same

Bug.csv_write(:filename => 'banana_slugs', :scope => Bug.banana_slugs)

write rows in the banana_slugs scope to 'banana_slugs.csv'

Book.csv_write(:filepath => '/home/wtn/books.csv')

specify output filepath (overrides any passed filename)

def Tree.csv_export_excluded_column_names; noncontent_column_names; end

avoid writing primary key and foreign keys to CSV

Box::CSV_DIR = Rails.root.join('csv', 'paper_products')

Override CSV_DIR

ActiveRecord::Base.csv_write(:scope => Toy.blue)

fails because ActiveRecord::Base.table_name raises exception

Pencil.csv_write(:column_names => %w{name hardness})

export only specified columns

Caveats

CSVRecords has been tested with ActiveRecord 3 on ruby 1.8.7 and 1.9.2-p0.

The modules in this plugin extend ActiveRecord::Base. If this annoys you, you may instead extend only the classes you need. You may also remove unneeded methods.

If you do not need the time-consuming ActiveRecord callbacks that run with create!, submit a patch or use fixtures instead.

Imports run in a database transaction, so you get all or none of your records.

Instead of using batches, the csv_write method performs one large query on the passed scope. While ActiveRecord objects are not instantiated for each row, I will implement scope pagination in the next version for cases with many rows (or extra chunky rows).

License

Copyright (c) 2010 William T Nelson, released under the Simplified BSD License. See the BSD-LICENSE file.