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/jeremyevans/sequel 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 all four use cases

• Last commit today
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 94% 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 jeremyevans/sequel repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jeremyevans/sequel.

What it runs against: a local clone of jeremyevans/sequel — 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 jeremyevans/sequel | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jeremyevans/sequel. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jeremyevans/sequel.git
#   cd sequel
#
# 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 jeremyevans/sequel and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jeremyevans/sequel(\\.git)?\\b" \\
  && ok "origin remote is jeremyevans/sequel" \\
  || miss "origin remote is not jeremyevans/sequel (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/sequel.rb" \\
  && ok "lib/sequel.rb" \\
  || miss "missing critical file: lib/sequel.rb"
test -f "lib/sequel/database.rb" \\
  && ok "lib/sequel/database.rb" \\
  || miss "missing critical file: lib/sequel/database.rb"
test -f "lib/sequel/dataset.rb" \\
  && ok "lib/sequel/dataset.rb" \\
  || miss "missing critical file: lib/sequel/dataset.rb"
test -f "lib/sequel/model.rb" \\
  && ok "lib/sequel/model.rb" \\
  || miss "missing critical file: lib/sequel/model.rb"
test -f "lib/sequel/adapters" \\
  && ok "lib/sequel/adapters" \\
  || miss "missing critical file: lib/sequel/adapters"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/jeremyevans/sequel"
  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).

Sequel is a comprehensive SQL database toolkit for Ruby that provides thread-safe connection pooling, a DSL for constructing SQL queries, an ORM layer for object-to-record mapping, and support for advanced database features (prepared statements, savepoints, two-phase commit, sharding). It abstracts away connection management and SQL formatting across 13+ database adapters (PostgreSQL, MySQL, SQLite3, Oracle, JDBC, etc.) so developers focus on application logic rather than database plumbing. Monolithic gem structure: core SQL/ORM logic lives in the main lib/ directory, organized by concern (dataset operations, model hooks, associations, adapters). Documentation is split into thematic guides (doc/dataset_basics.rdoc, doc/association_basics.rdoc, doc/model_plugins.rdoc). Database-specific adapters are implemented as plugins. The bin/sequel CLI provides a REPL and migration tooling.

Ruby developers and teams building database-backed applications who need a mature, database-agnostic ORM and query builder. Users range from those writing simple CRUD apps to engineers handling complex schemas with advanced features like multi-database sharding and transaction isolation.

Highly mature and actively maintained. The repo shows 7MB+ of Ruby code across 60+ documented guides, versioned back to 1.0 with detailed release notes through 3.1.0, a formal CI pipeline (.github/workflows/ci.yml), comprehensive test coverage implied by the large codebase, and ongoing commits. This is production-ready with a 15+ year history.

Extremely low risk. Single maintainer (jeremyevans) is a known veteran in the Ruby ecosystem; however, there is inherent single-person-of-failure risk. The mature version numbering (3.1.0) and extensive documentation minimize breaking-change surprise. No visible signs of abandonment, but community contributions may be modest given the maintainer model.

Based on the file structure, active maintenance includes version 3.1.0 release notes, a CI workflow configured in .github/workflows/ci.yml, and multiple database adapter support. The CHANGELOG and versioned release notes indicate regular updates; specific current PRs/issues are not visible in the provided data, but the maintained nature of the release notes suggests ongoing patch and feature work.

git clone git://github.com/jeremyevans/sequel.git
cd sequel
gem install sequel
sequel sqlite://test.db  # Launch the interactive console

Daily commands: No traditional 'dev server.' Sequel is a library, not an app. To test locally: rake (runs test suite; Rakefile present). To explore: bundle exec irb then require 'sequel' or use bin/sequel sqlite://memory for an interactive console.

• lib/sequel.rb — Main entry point that loads all core Sequel modules; every contributor must understand the top-level architecture and dependency loading order.
• lib/sequel/database.rb — Core Database class that manages connections, adapters, and query execution; foundational to all database operations.
• lib/sequel/dataset.rb — Dataset class implementing the query DSL and lazy evaluation; central to Sequel's fluent interface and SQL generation.
• lib/sequel/model.rb — ORM layer providing the Model base class for record mapping and associations; required reading for understanding the active record pattern implementation.
• lib/sequel/adapters — Database adapter implementations (MySQL, PostgreSQL, SQLite, etc.); essential for understanding multi-database support architecture.
• README.rdoc — High-level overview of Sequel's capabilities and philosophy; establishes scope and design principles.
• CONTRIBUTING — Contribution guidelines covering code standards, testing requirements, and patch submission process.

Add a New Database Adapter

1. Create a new adapter file in lib/sequel/adapters/ (e.g., lib/sequel/adapters/mydb.rb) that extends the Database class (lib/sequel/adapters/mydb.rb)
2. Implement required methods: connect, disconnect, execute, dataset_class, and database_type (lib/sequel/adapters/mydb.rb)
3. Register the adapter in lib/sequel.rb by adding it to the require list and adapter_class mapping (lib/sequel.rb)
4. Create dialect-specific Dataset subclass for SQL generation if needed (lib/sequel/adapters/mydb/dataset.rb) (lib/sequel/adapters/mydb/dataset.rb)

Add a New Model Plugin

1. Create a new file in lib/sequel/model/plugins/ (e.g., lib/sequel/model/plugins/my_plugin.rb) (lib/sequel/model/plugins/my_plugin.rb)
2. Define a module that extends or modifies Model behavior; use apply method for configuration (lib/sequel/model/plugins/my_plugin.rb)
3. Add plugin to the Model class plugin registry in lib/sequel/model.rb (lib/sequel/model.rb)
4. Document plugin usage in doc/model_plugins.rdoc with examples (doc/model_plugins.rdoc)

Add a New Dataset Method

1. Identify which concern the method belongs to (filtering, query, actions, etc.) and open the appropriate file in lib/sequel/dataset/ (lib/sequel/dataset/query.rb)
2. Add the method to the relevant Dataset module, following Sequel's naming conventions (e.g., where, select, join) (lib/sequel/dataset/query.rb)
3. Ensure the method returns a cloned dataset (maintaining immutability) or performs the operation and returns results (lib/sequel/dataset.rb)
4. Add tests in spec/core/dataset_spec.rb demonstrating the new method with various database adapters (spec/core/dataset_spec.rb)

Add Database-Specific Type Handling

1. Locate the adapter file (lib/sequel/adapters/mydb.rb) and identify the type conversion methods (lib/sequel/adapters/mydb.rb)
2. Add custom type mappings in the adapter's type_literal_generic method to handle your new type (lib/sequel/adapters/mydb.rb)
3. Override result_set_columns to properly deserialize custom types from database results (lib/sequel/adapters/mydb.rb)
4. Add adapter-specific tests in spec/adapters/mydb_spec.rb verifying type serialization/deserialization (spec/adapters/mydb_spec.rb)

• Ruby (MRI, JRuby, TruffleRuby) — Sequel is designed for Ruby applications; dynamically typed language enables flexible DSL construction and metaprogramming for query building.
• Thread-safe Connection Pooling — Essential for multi-threaded Ruby applications (Puma, Sidekiq); prevents database connection exhaustion and ensures thread safety across the ORM.
• Lazy Evaluation (Dataset pattern) — Datasets are immutable and only executed when terminal operations are called (all, first, count); enables query optimization and composition without premature execution.
• Adapter Pattern — Abstracts database-specific SQL dialects and features; allows single ORM to work with MySQL, PostgreSQL, SQLite, Oracle, JDBC, etc. with minimal code duplication.
• Hook/Callback System — Models support lifecycle hooks (before_create, after_update) for validation, logging, and business logic; decouples concerns in active record pattern.

• Immutable Dataset pattern with cloning on each operation

  • Why: Prevents hidden mutation and state leakage in complex queries; simplifies reasoning about query composition.
  • Consequence: Slightly higher memory and GC pressure compared to mutable query builders; trade-off acceptable for correctness and thread safety.

• Eager loading via separate queries instead of JOINs by default

  • Why: More flexible (works across all databases, handles complex associations); reduces N+1 query problem without complex SQL generation.
  • Consequence: Developers must explicitly call eager_load or use associations; requires awareness of loading strategy to avoid performance regressions.

• Single library supporting 10+ database adapters

  • Why: Provides portability and flexibility for applications that may change databases or support multiple backends.
  • Consequence: Core ORM logic must remain adapter-agnostic; adapter-specific optimizations (e.g., PostgreSQL arrays) are opt-in features.

• No global state; explicit database instance per application

  • Why: Enables multi-database support and concurrent applications in same process; simplifies testing and eliminates magic variables.
  • Consequence: undefined

No critical hidden traps visible in the file structure, but: (1) The library is database-agnostic, so adapter choice and driver installation are prerequisite (e.g., gem 'sqlite3' for SQLite); (2) The extensive plugin system (doc/model_plugins.rdoc) means core behavior can be extended or overridden, which requires reading docs before assuming standard behavior; (3) Transaction and connection pool behavior varies by adapter; (4) The single maintainer means issue response may not be instant, so read closed issues and forums before reporting.

• Lazy Dataset Evaluation — Understanding that Sequel datasets are not executed until .all, .first, or iteration occurs is critical for avoiding N+1 queries and for chaining complex filters efficiently.
• Prepared Statements & Bind Variables — Sequel's support for parameterized queries via bind variables is essential for SQL injection prevention and performance; differs significantly from string interpolation.
• Connection Pooling & Thread Safety — Sequel handles connection pool management automatically, but understanding pool size, timeouts, and thread safety is critical for production apps with concurrent requests.
• Adapter Pattern for Database Abstraction — Sequel's adapter architecture (lib/sequel/adapters/) abstracts dialect differences; knowing how to write adapter-agnostic code vs. adapter-specific SQL is key.
• Association Eager Loading & Lazy Loading — Sequel's model associations support both strategies; understanding when to use .eager vs. implicit loading prevents performance regressions in ORM queries.
• Savepoints & Transaction Isolation — Sequel exposes savepoints and transaction isolation levels (READ COMMITTED, SERIALIZABLE, etc.) as first-class features; critical for building robust concurrent applications.
• Plugin Architecture & Model Hooks — Sequel's extensibility via plugins and before/after hooks (doc/model_hooks.rdoc) allows non-invasive customization; understanding this pattern prevents tight coupling and enables library integration.

• rails/rails — Active Record is Rails' built-in ORM; Sequel is a standalone alternative popular with Sinatra and non-Rails projects.
• dry-rb/dry-system — Complementary Ruby toolkit; Sequel users often pair it with dry-rb for schema validation and dependency injection in larger apps.
• sinatra/sinatra — Lightweight web framework that pairs naturally with Sequel for building lean database-backed APIs without Rails overhead.
• jeremyevans/roda — Same maintainer's minimal web framework; designed as a lightweight routing layer to complement Sequel ORM.
• lotus/model — Hanami's ORM, a spiritual competitor emphasizing separation of concerns; useful to study alternative ORM design philosophy.

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 documentation for Sequel's sharding capabilities

The README mentions 'database sharding' as an advanced feature, but there is no dedicated documentation file in doc/ for this feature. Given that sharding is a complex distributed database concept, new users would benefit from a doc/sharding.rdoc file explaining patterns, configuration, and examples. This is a high-value addition since sharding is explicitly marketed but not documented.

• [ ] Create doc/sharding.rdoc following the existing documentation style (see doc/querying.rdoc and doc/advanced_associations.rdoc for patterns)
• [ ] Document sharding configuration patterns with code examples
• [ ] Add section on shard selection strategies and key distribution
• [ ] Reference sharding concepts in doc/opening_databases.rdoc
• [ ] Add sharding to the appropriate release notes file (likely doc/release_notes/3.28.0.txt or newer)

Create CI workflow for testing against multiple Ruby versions with JRuby

The .github/workflows/ci.yml exists but the repo supports JDBC adapter (mentioned in README). Currently there's likely no explicit JRuby testing in CI. Adding a dedicated JRuby test matrix would ensure JDBC adapter compatibility and catch JRuby-specific issues early, which is critical for a database toolkit supporting multiple adapters.

• [ ] Examine current .github/workflows/ci.yml to identify existing Ruby version matrix
• [ ] Add JRuby testing job with JDBC adapter-specific test suites
• [ ] Configure conditional steps to skip non-JDBC tests when running on JRuby
• [ ] Ensure .ci.gemfile includes JDBC driver dependencies for JRuby builds
• [ ] Document the JRuby CI setup in CONTRIBUTING file

Add dedicated documentation for Trilogy adapter configuration and usage

The README lists 'Trilogy' as a supported adapter (a newer MySQL client library), but there's no doc/trilogy.rdoc file. Similar to doc/postgresql.rdoc and doc/mssql_stored_procedures.rdoc, Trilogy users need adapter-specific documentation covering connection strings, specific features, performance characteristics, and potential gotchas. This fills a documentation gap for a relatively modern adapter.

• [ ] Create doc/trilogy.rdoc following the pattern of doc/postgresql.rdoc
• [ ] Document Trilogy-specific connection URI format and options
• [ ] Add configuration examples for common use cases (connection pooling, SSL, etc.)
• [ ] Document any Trilogy-specific SQL features or limitations compared to other MySQL adapters
• [ ] Add troubleshooting section for common Trilogy+Sequel integration issues
• [ ] Reference the new file in README.rdoc adapter section

• Add comprehensive examples to doc/prepared_statements.rdoc showing parameterized query patterns across different adapters (currently exists but could have adapter-specific recipes).
• Implement a regression test suite in the spec/ folder comparing query output across SQLite, PostgreSQL, and MySQL adapters to catch dialect inconsistencies.
• Document the plugin authoring pattern with a complete walkthrough example in doc/model_plugins.rdoc (currently reference-style; could benefit from step-by-step plugin creation guide).

Sequel is a mature database toolkit with generally secure design principles (parameterized queries via DSL, prepared statement support). However, security heavily depends on proper usage by developers. Main risks include: (1) SQL injection through misuse of raw SQL or improper string interpolation, (2) mass assignment vulnerabilities if attribute whitelisting isn't properly configured, (3) inconsistent security across multiple database adapters, and (4) lack of visible security policy/disclosure guidelines. The toolkit itself appears well-designed for security, but developer education and documentation are critical areas for improvement. No critical vulnerabilities were identified in the codebase structure itself, but the extensive SQL construction capability creates inherent risks if misused.

• High · Potential SQL Injection Risk in Database Toolkit — Core lib/ directory - dataset and query construction modules. As a database toolkit that constructs SQL queries, Sequel has significant SQL injection attack surface. While the DSL approach mitigates many risks, improper use of raw SQL, string interpolation, or dynamic query construction could expose applications to SQL injection attacks. The codebase's core functionality involves converting Ruby code to SQL, which requires careful handling of user inputs. Fix: Ensure all user inputs are parameterized through bound variables and prepared statements. Use the DSL exclusively rather than raw SQL interpolation. Implement input validation and output encoding. Review and document safe vs unsafe API patterns. Add security warnings in documentation about raw SQL usage.
• Medium · Multiple Database Adapter Support Increases Attack Surface — lib/sequel/adapters/ directory. Sequel supports 11+ database adapters (MySQL, PostgreSQL, SQLite3, Oracle, JDBC, etc.). Each adapter may have different vulnerability profiles, security features, and default configurations. Inconsistent security implementations across adapters could lead to vulnerabilities in specific database configurations. Fix: Maintain security audit trails for each adapter separately. Ensure consistent security handling across all adapters. Document adapter-specific security considerations and recommendations for each database type. Implement adapter-agnostic security tests.
• Medium · ORM Mass Assignment Vulnerability Risk — doc/mass_assignment.rdoc, ORM layer implementation. The README mentions 'mass assignment' support and there is dedicated documentation (doc/mass_assignment.rdoc). Improper mass assignment handling can allow attackers to modify unintended database fields. If users don't properly whitelist/blacklist attributes, sensitive fields could be exposed to manipulation. Fix: Ensure strong attribute whitelisting is the default behavior. Require explicit permission for mass assignment. Provide clear examples of secure mass assignment patterns. Document which attributes should never be mass-assigned (e.g., admin flags, IDs). Implement warnings for dangerous patterns.
• Medium · Prepared Statements and Bound Variables Implementation — doc/prepared_statements.rdoc, core query execution modules. While prepared statements are mentioned as supported, improper implementation or misuse could negate their security benefits. If developers use string interpolation instead of parameter binding with prepared statements, SQL injection vulnerabilities would persist. Fix: Provide comprehensive examples of prepared statement usage. Make parameter binding the default and easiest approach. Add linting/detection for unsafe patterns. Document performance considerations of prepared statements. Implement warnings if raw SQL is used with variables.
• Low · Missing Security Headers Documentation — Documentation and examples. No visible security headers configuration or documentation in the provided file structure. While Sequel is a database toolkit (not a web framework), applications using it should implement proper security headers. Fix: Add security best practices documentation for web applications using Sequel. Include guidance on web framework integration security considerations.
• Low · No Visible SECURITY.md or Security Policy — Repository root. No dedicated security policy, vulnerability disclosure guidelines, or security.md file visible in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines. Consider adding security reporting instructions in GitHub repository settings. Document security update process and version support policy.
• Low · Dependency Management Visibility — Gemfile, sequel.gemspec. No dependency files (Gemfile, gemspec) were provided in the analysis context. Cannot assess for known vulnerable dependencies. Fix: Regularly audit dependencies for known vulnerabilities using tools like bundle-audit or Dependabot. Keep dependencies updated. Document minimum required versions for security patches.

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.