🐜 Antz

Declarative CSV-to-ActiveRecord importer with dependency resolution

Import structured CSV data into your Rails (or plain ActiveRecord) app — safely, clearly, and in the right order.

Ever needed to seed a database from CSVs…
but your products depend on categories, which depend on vendors?
And you don’t want to write fragile, one-off scripts?

Antz lets you:

• Declare what data goes where — like a recipe.
• Map and transform CSV columns to model attributes.
• Automatically resolve dependencies (e.g., import users before orders).
• Batch-process large files efficiently.
• Dry-run safely before touching your DB.

All with a clean, readable Ruby DSL using the #table method.

gem "antz"

Then run:

bundle install

✅ Requires Ruby ≥ 3.2 and ActiveRecord ≥ 6.0.

# config/initializers/antz.rb

Antz.configure do |c|
  c.base_dir = Rails.root.join("data", "csv_imports")  # where your CSVs live
  c.batch_size = 500                                   # default: 200
end

import = Antz.define do
  table :categories do
    map :id
    map :name
  end

  table :products, depends_on: :categories do
    map :name
    map :category_id
    map(:price_cents) { |v| v.to_i * 100 }  # transform on the fly
  end

  table :users do
    map :full_name, to: :name
    map :email
    map(:age) { |v| v&.to_i }
  end
end

💡 CSV filenames default to pluralized table names (e.g., products.csv).
You can override with file: "my_custom_file.csv".

# Preview what would happen (no DB writes)
import.run(dry_run: true)

# Actually import
import.run

✅ Handles upsert_all (PostgreSQL/MySQL) when possible. Falls back to insert_all.

Each file must have headers matching your source column names:

categories.csv

id,name
1,Fruits
2,Vegetables

products.csv

name,category_id,price_cents
Apple,1,99
Carrot,2,59

table :items, model: Product do
  map :title, to: :name
end

table :logs, on_duplicate: :ignore do
  map :message
end

table :events, file: "/mnt/data/events_export.csv" do
  map :timestamp
end

Antz is thoroughly tested with RSpec. To run the suite:

bin/setup
bundle exec rspec

Fixtures use in-memory SQLite — no external DB needed.

We follow Conventional Commits.
Please use npm run commit (or npx cz) to create structured commits.

Releases are automated via npm run release.

MIT © 2025 Ilmir Karimov

• The pain of one-off CSV import scripts
• The need for reproducible, maintainable data bootstrapping

👉 Found a bug? Have an idea?
Open an issue or PR on GitHub!