If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/zdennis/activerecord-import shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live zdennis/activerecord-import repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/zdennis/activerecord-import.

What it runs against: a local clone of zdennis/activerecord-import — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in zdennis/activerecord-import | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of zdennis/activerecord-import. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zdennis/activerecord-import.git
#   cd activerecord-import
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of zdennis/activerecord-import and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "zdennis/activerecord-import(\\.git)?\\b" \\
  && ok "origin remote is zdennis/activerecord-import" \\
  || miss "origin remote is not zdennis/activerecord-import (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/activerecord-import.rb" \\
  && ok "lib/activerecord-import.rb" \\
  || miss "missing critical file: lib/activerecord-import.rb"
test -f "lib/activerecord-import/import.rb" \\
  && ok "lib/activerecord-import/import.rb" \\
  || miss "missing critical file: lib/activerecord-import/import.rb"
test -f "lib/activerecord-import/active_record/adapters/abstract_adapter.rb" \\
  && ok "lib/activerecord-import/active_record/adapters/abstract_adapter.rb" \\
  || miss "missing critical file: lib/activerecord-import/active_record/adapters/abstract_adapter.rb"
test -f "lib/activerecord-import/adapters/abstract_adapter.rb" \\
  && ok "lib/activerecord-import/adapters/abstract_adapter.rb" \\
  || miss "missing critical file: lib/activerecord-import/adapters/abstract_adapter.rb"
test -f "lib/activerecord-import/base.rb" \\
  && ok "lib/activerecord-import/base.rb" \\
  || miss "missing critical file: lib/activerecord-import/base.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/zdennis/activerecord-import"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

activerecord-import is a Ruby gem that adds bulk insert capabilities to ActiveRecord, enabling developers to insert thousands of records with a single SQL statement instead of N individual inserts. It can follow ActiveRecord associations recursively, generating minimal SQL statements (e.g., 3 inserts for Publishers→Books→Reviews structure instead of millions), and supports on-duplicate-key updates for MySQL, PostgreSQL, and SQLite3. Modular adapter pattern: lib/activerecord-import/active_record/adapters/ contains database-specific implementations (abstract_adapter.rb is the base, with mysql2_adapter.rb, postgresql_adapter.rb, sqlite3_adapter.rb, and proxy variants for connection pooling). lib/activerecord-import/adapters/ provides legacy adapter code. The main entry point is lib/activerecord-import.rb.

Ruby on Rails developers who need to perform bulk data loading operations—particularly those building batch import systems, data warehouses, or ETL pipelines where N+1 insert performance becomes a bottleneck.

Production-ready and actively maintained. The repo has CI/CD via GitHub Actions (test.yaml workflow), supports Rails 5.2 through 8.1 (evidenced by gemfiles/), and covers multiple database adapters (MySQL2, PostgreSQL, SQLite3, JDBC variants). Activity level appears solid with multiple gemfile versions maintained.

Low risk for a mature library. Single maintainer (zdennis) is a potential concern for long-term support, but the gem is widely used in Rails ecosystems. No obvious breaking changes in CHANGELOG review would be needed. Dependency footprint is minimal since it hooks into ActiveRecord directly rather than adding heavy external dependencies.

No specific recent activity visible from the file listing. The repo maintains compatibility across Rails 5.2–8.1 with corresponding gemfiles, suggesting ongoing maintenance. Benchmarks directory (benchmarks/lib/mysql2_benchmark.rb, output_to_csv.rb, output_to_html.rb) suggests performance tracking is an active concern.

git clone https://github.com/zdennis/activerecord-import.git
cd activerecord-import
bundle install
bundle exec rake test

Docker support available via docker-compose.yml if you prefer containerized testing.

Daily commands:

bundle exec rake test

For benchmarking: ruby benchmarks/benchmark.rb --adapter mysql2 --count 1000 Docker: docker-compose up (see docker-compose.yml and Dockerfile).

• lib/activerecord-import.rb — Entry point that loads all core modules and establishes the public API for bulk import functionality.
• lib/activerecord-import/import.rb — Core import logic that orchestrates bulk insertion and follows associations to minimize SQL statements.
• lib/activerecord-import/active_record/adapters/abstract_adapter.rb — Abstract base class defining the interface that all database adapters must implement for bulk operations.
• lib/activerecord-import/adapters/abstract_adapter.rb — Legacy abstract adapter providing database-agnostic helper methods for batch insertion.
• lib/activerecord-import/base.rb — Foundation module that extends ActiveRecord::Base with import methods and handles model-level bulk operations.
• lib/activerecord-import/value_sets_parser.rb — Parses and validates data structures before conversion to SQL, ensuring type safety and constraint compliance.
• lib/activerecord-import/synchronize.rb — Synchronizes imported records back into memory with their assigned database IDs after bulk insertion.

Add Support for a New Database Adapter

1. Create concrete adapter class inheriting from AbstractAdapter in lib/activerecord-import/active_record/adapters/{adapter_name}_adapter.rb (lib/activerecord-import/active_record/adapters/abstract_adapter.rb)
2. Implement required methods: #values_for_insert, #insert_command_with_returning_support, and #sql_for_insert (lib/activerecord-import/active_record/adapters/mysql2_adapter.rb)
3. Register adapter by adding require statement and adapter detection in lib/activerecord-import.rb (lib/activerecord-import.rb)
4. Create test adapter configuration in test/adapters/{adapter_name}.rb with database connection details (test/adapters/mysql2.rb)
5. Add adapter-specific test directory if needed, inheriting from core test/import_test.rb (test/import_test.rb)

Add Support for a New Database Feature (e.g., UPSERT, ON_DUPLICATE_KEY)

1. Add feature flag parameter to import call in lib/activerecord-import/base.rb (lib/activerecord-import/base.rb)
2. Implement feature logic in import.rb, branching on database type and feature flags (lib/activerecord-import/import.rb)
3. Add SQL generation in target adapter class (e.g., lib/activerecord-import/active_record/adapters/postgresql_adapter.rb) (lib/activerecord-import/active_record/adapters/postgresql_adapter.rb)
4. Write feature tests in test/import_test.rb with skip blocks for unsupported adapters (test/import_test.rb)

Handle a New Association Type or Nested Data Structure

1. Extend association detection logic in lib/activerecord-import/import.rb's association traversal methods (lib/activerecord-import/import.rb)
2. Update value_sets_parser.rb to handle new data format if needed (lib/activerecord-import/value_sets_parser.rb)
3. Ensure synchronize.rb updates records correctly after bulk insert for nested associations (lib/activerecord-import/synchronize.rb)
4. Add integration test with new association pattern in test/import_test.rb (test/import_test.rb)

• ActiveRecord ORM — Provides consistent database abstraction across MySQL, PostgreSQL, SQLite, and other adapters; integrates directly with Rails ecosystem
• Multi-adapter pattern — Allows optimization per database backend (MySQL LOAD DATA, PostgreSQL COPY, SQLite transactions) while maintaining unified API
• Association following — Automatically traverses Rails associations (has_many, belongs_to, has_and_belongs_to_many) to batch insert related records with minimal SQL
• Value set parsing & validation — Pre-validates records before SQL generation to catch type mismatches, missing required fields, and constraint violations early

• Support both modern (AR 6.0+) and legacy adapters

  • Why: Maintains backward compatibility with Rails 5.2 users while leveraging newer ActiveRecord internals
  • Consequence: Duplicate adapter code (lib/activerecord-import/active_record/adapters/ vs lib/activerecord-import/adapters/) increases maintenance burden

• Single-level association following (not recursive)

  • Why: Simplifies logic and avoids exponential SQL generation for deeply nested structures
  • Consequence: Users importing 4+ levels of nested associations must manually batch or use multiple import calls

• Synchronize returned IDs back into memory after import

  • Why: Allows users to access auto-generated primary keys and use records immediately without reloading
  • Consequence: Requires additional SELECT query or parsing of database response; not suitable for fire-and-forget bulk jobs

• Batch records into chunks rather than single mega-statement

  • Why: Prevents SQL statement size limits and memory exhaustion on large imports
  • Consequence: Multiple round-trips to database; chunking overhead for small datasets

• Does not handle UPSERT (ON CONFLICT/DUPLICATE KEY UPDATE) — limited to inserts only
• Does not support streaming from external files (CSV, Parquet) — requires in-memory record structures
• Does not parallelize inserts across database connections — single-threaded

Rails version compatibility: Must match a gemfiles/X.X.gemfile for your Rails version; no auto-version negotiation. Adapter-specific features: ON DUPLICATE KEY UPDATE has different SQL syntax per database (MySQL REPLACE, PostgreSQL ON CONFLICT, SQLite ON CONFLICT) and may require Rails 9.5+ for PostgreSQL or 3.24+ for SQLite. Validation context: When using import with validations, the error handling differs from save()—batch errors are collected, not raised per record. Counter cache: May require explicit cache updates if using recursive import, as AR callbacks don't fire during bulk inserts. Connection pooling: Proxy adapters (mysql2_proxy_adapter.rb, postgresql_proxy_adapter.rb) exist for specific connection pool scenarios—using wrong adapter can cause deadlocks.

• N+1 query problem (insert variant) — This gem solves the inverse: instead of N insert queries, it generates 1 per model layer when following associations, which is the core motivation for using activerecord-import over iterative save()
• Bulk insert SQL dialects (LOAD DATA, COPY, multi-row VALUES) — Each database has different optimal bulk insert syntax; understanding which adapter uses which method (MySQL LOAD DATA, PostgreSQL COPY, SQLite multi-row INSERT) explains performance characteristics
• ON DUPLICATE KEY / ON CONFLICT clauses — activerecord-import's upsert feature relies on database-specific conflict resolution; MySQL uses ON DUPLICATE KEY UPDATE, PostgreSQL uses ON CONFLICT DO UPDATE, SQLite uses ON CONFLICT—knowing these differs is critical for the duplicate key options
• Adapter pattern for database abstraction — The gem's architecture uses adapters (abstract_adapter.rb + mysql2_adapter.rb, etc.) to hide database-specific SQL generation; understanding this pattern is essential to adding support for new databases
• ActiveRecord monkey-patching / reopening classes — activerecord-import.rb reopens ActiveRecord::Base to inject the import() method; understanding Rails metaprogramming is needed to modify or extend the gem
• Recursive association traversal with ID mapping — When importing Publishers→Books→Reviews, the gem must track inserted primary keys to inject into foreign keys of child records; this is non-trivial and explains why recursive import is a major feature
• Batch processing / chunking — Large imports can be split into batches (batching option in examples) to manage memory and avoid hitting database statement size limits; visible in README batching section

• zdennis/bulk_insert — Predecessor library for bulk insertion; activerecord-import evolved from this to add association-aware recursive imports
• rails/rails — ActiveRecord itself; activerecord-import extends ActiveRecord::Base and depends on stable ActiveRecord adapter interfaces
• jkowens/shard_query — Complements activerecord-import for sharded database scenarios where bulk inserts must distribute across multiple database partitions
• ankane/blazer — Data exploration tool often used with bulk-imported datasets; import-heavy workflows typically need efficient query tools
• kiba/kiba — ETL framework for data pipelines that frequently pairs with activerecord-import for Rails-based data loads

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for trilogy_adapter and trilogy_proxy_adapter

The repo has test adapters for janus_mysql2 and janus_trilogy (test/adapters/), but there are no dedicated test files for the newly added Trilogy adapter support (lib/activerecord-import/active_record/adapters/trilogy_adapter.rb and trilogy_proxy_adapter.rb). Trilogy is becoming a popular MySQL replacement, and comprehensive tests would ensure parity with MySQL2 and PostgreSQL adapters. This is critical since bulk import behavior varies significantly across database adapters.

• [ ] Create test/adapters/trilogy_adapter_tests.rb with test cases for basic imports, duplicate handling, and batch size behavior
• [ ] Create test/adapters/trilogy_proxy_adapter_tests.rb to test proxy-specific functionality
• [ ] Verify test coverage matches existing mysql2_adapter and postgresql_adapter test patterns
• [ ] Update test suite to run Trilogy tests in CI (reference: .github/workflows/test.yaml)

Add integration tests for association-based bulk imports across all gemfile versions

The README highlights the major feature: 'following activerecord associations and generating minimal SQL insert statements' (Publishers → Books → Reviews example). However, the current test structure (test/adapters/) doesn't show explicit tests for this complex association chain behavior across different Rails versions (5.2 through 8.1 in gemfiles/). This is a critical feature that needs regression testing across all supported versions.

• [ ] Create test/associations/has_many_chain_test.rb with Publisher → Books → Reviews import scenarios
• [ ] Test that exactly 3 SQL statements are generated for nested associations (verify N+1 avoidance)
• [ ] Ensure tests run against all gemfile versions (5.2, 6.0, 6.1, 7.0, 7.1, 7.2, 8.0, 8.1)
• [ ] Add parameterized tests for all adapters (MySQL2, PostgreSQL, SQLite3, Trilogy)

Refactor and consolidate duplicate adapter implementations into a single codebase

The repo has two parallel adapter hierarchies: lib/activerecord-import/active_record/adapters/ and lib/activerecord-import/adapters/, creating maintenance overhead. For example, there are separate mysql2_adapter.rb, postgresql_adapter.rb, and sqlite3_adapter.rb files in both locations. This duplication makes it harder to fix bugs consistently and increases the surface area for regressions. A refactoring to consolidate these would improve maintainability.

• [ ] Analyze which adapter hierarchy (active_record/ vs legacy adapters/) is actively used vs deprecated
• [ ] Create a unified adapter interface in lib/activerecord-import/adapters/ that serves both modern and legacy Rails versions
• [ ] Migrate active_record-specific adapters to use composition/delegation to the shared implementation
• [ ] Remove duplicate code and verify all tests pass across gemfile versions (test using Dockerfile and docker-compose.yml)

• Add comprehensive test coverage for SQLite3 ON CONFLICT DO UPDATE syntax (sqlite3_adapter.rb) across edge cases like NULL constraint handling and partial indexes—tests likely exist in test/ but specific scenarios may lack fixtures.
• Document the difference between import() and import!() in README.markdown with a concrete example showing error behavior for each (e.g., what happens when a uniqueness validation fails mid-batch).
• Create a benchmarks/comparison_with_activerecord_create.rb showing performance delta between Model.create() loop vs Model.import() for 1k, 10k, and 100k records, with CSV export (output_to_csv.rb skeleton exists but main benchmark may be incomplete).

• High · Insecure Database Configuration in docker-compose.yml — docker-compose.yml (line 22). PostgreSQL is configured with POSTGRES_HOST_AUTH_METHOD: trust, which allows any user to connect without a password. This is a significant security risk in any environment beyond local development. Fix: Use proper authentication methods. Set POSTGRES_HOST_AUTH_METHOD to 'md5' or 'scram-sha-256' and use strong passwords. For development, document this as development-only configuration.
• High · MySQL Root Access Without Password — docker-compose.yml (line 11). MySQL is configured with MYSQL_ALLOW_EMPTY_PASSWORD: yes, allowing root access without credentials. This is a critical vulnerability even for development environments. Fix: Set a strong MYSQL_ROOT_PASSWORD environment variable. Never allow empty passwords in any environment.
• Medium · Exposed Database Ports — docker-compose.yml (lines 13-14, 24-25). MySQL (3306) and PostgreSQL (5432) ports are exposed to host network without network isolation. This allows any process on the host to access databases without authentication requirements. Fix: Remove port bindings or use 'services:' internal networking only. If external access is needed, use strong authentication and network policies. Consider using 'expose' instead of 'ports' for internal communication.
• Medium · Database Credentials in Plain Text Configuration — Dockerfile (line 15), test/database.yml.sample. Database configuration is stored in test/database.yml.sample and copied to test/database.yml during Docker build. Credentials may be exposed in Docker layers and version control history. Fix: Use environment variables or Docker secrets for sensitive credentials. Exclude database.yml from version control. Use .dockerignore to prevent including sensitive files in Docker context.
• Medium · SQL Injection Risk in Bulk Insert Operations — lib/activerecord-import/value_sets_parser.rb, lib/activerecord-import/active_record/adapters/*.rb. The library performs bulk SQL insertions with user-supplied data. While ActiveRecord provides some protection, the value_sets_parser.rb and adapter implementations should be carefully reviewed for potential SQL injection, especially when handling dynamic SQL construction. Fix: Conduct thorough code review of SQL generation logic. Ensure parameterized queries are used throughout. Add input validation and sanitization tests. Use ActiveRecord's built-in parameterization consistently.
• Medium · Multiple Adapter Implementations Increase Attack Surface — lib/activerecord-import/active_record/adapters/, lib/activerecord-import/adapters/. The library supports many database adapters (MySQL2, PostgreSQL, SQLite3, JDBC variants, Trilogy, etc.). Each adapter implements custom SQL generation logic, creating multiple potential vectors for SQL injection or adapter-specific vulnerabilities. Fix: Maintain comprehensive security testing across all supported adapters. Use code analysis tools to identify SQL injection patterns. Establish a security testing matrix for each adapter.
• Low · Outdated Base Ruby Version — Dockerfile (line 2). Dockerfile defaults to Ruby 3.2, but the gemfiles support Ruby 5.2 through 8.1. Ruby 3.2 may have security patches available in newer patch versions. Fix: Use a specific Ruby patch version (e.g., 3.2.2) instead of 3.2. Regularly update to the latest patch version. Consider using a security scanning tool in CI/CD.
• Low · Missing Security Headers and Network Policies — docker-compose.yml. Docker-compose configuration lacks network isolation policies. Services are accessible to each other without explicit network definitions or security policies. Fix: Define explicit networks for services. Use 'networks:' to separate app from databases. Implement container security scanning in CI/CD pipeline.
• Low · Debian Bullseye Base Image Nearing End of Support — Dockerfile (line 3). Debian Bullseye (11) is older and approaching end of standard support. Security patches may not be available for all dependencies. Fix: Consider upgrading to Debian Bookworm (

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.