Sequel: the Ruby database toolkit that keeps SQL in view

What Sequel solves for Ruby applications that outgrow hand-written SQL

The README describes Sequel as a SQL database access toolkit for Ruby, and that framing matters. It is not a full-stack framework and it does not try to hide the database. The project targets developers who are comfortable with SQL but tired of string concatenation, manual connection handling and adapter-specific quoting. Sequel takes over connection maintenance, SQL formatting and record fetching, in the README's own words, so the application code can focus on queries and results.

The audience is narrow and fairly specific. If you write Ruby services that talk to PostgreSQL, MySQL, SQLite3, Oracle, JDBC, ODBC, TinyTDS, Trilogy, IBM_DB, ADO, Amalgalite or SQLAnywhere, Sequel ships an adapter for each of those names. If you want an ORM but also want to drop to raw SQL without switching libraries, the same toolkit covers both. If you want a framework to generate your models, migrations and controllers, Sequel is the wrong layer.

Datasets, chainability and lazy evaluation in the Sequel query layer

The core abstraction is the dataset. A Dataset object encapsulates an SQL query and supports chainability, so you build a query by appending conditions and only execute it when you ask for records. The README's example, DB[:countries].where(region: 'Middle East').avg(:GDP), is stated to be equivalent to SELECT avg(GDP) FROM countries WHERE region = 'Middle East'. There is no hidden eager load and no implicit query per row.

Datasets are frozen, which the README notes makes them safe to store and reuse. You can assign a filtered dataset to a variable, call order or each on it later, and the underlying query is re-run at that point. Results arrive as hashes and are read through an Enumerable interface. Sequel adds convenience methods on top: map(:name) returns a single column as an array, map([:id, :name]) returns arrays of pairs, and as_hash(:name, :area) returns a hash keyed by one column with another as the value. That last method is a small thing, but it removes a lot of each_with_object boilerplate.

The ORM layer sits above this. Sequel::Model maps records to Ruby objects and handles associated records, while the dataset layer remains available underneath. The README also lists advanced features that are unusual to find in one Ruby library: prepared statements, bound variables, savepoints, two-phase commit, transaction isolation, primary/replica configurations and database sharding. Those are database-level capabilities, not application-level conveniences, and their presence in the README is the clearest signal of who the library is built for.

Installing Sequel and running the README's first example

Installation is a single gem command. The README gives no bundler-specific instructions and no version pinning advice, so the gem name is the only thing to copy exactly.

gem install sequel

The README's short example uses an in-memory SQLite database, so it also needs the sqlite3 gem available. The script creates a table, inserts three rows and prints a count and an average.

require 'sequel'

DB = Sequel.sqlite # memory database, requires sqlite3

DB.create_table :items do
  primary_key :id
  String :name
  Float :price
end

items = DB[:items]
items.insert(name: 'abc', price: rand * 100)
items.insert(name: 'def', price: rand * 100)
items.insert(name: 'ghi', price: rand * 100)

puts "Item count: #{items.count}"
puts "The average price is: #{items.avg(:price)}"

Running that prints an item count of 3 and an average price somewhere between 0 and 100, since the prices come from rand. Nothing is persisted; the memory database disappears when the process exits.

For a real database, the README shows Sequel.connect with a URL, including credentials and an optional connection pool size and logger.

require 'sequel'
DB = Sequel.connect('postgres://user:password@host:port/database_name',
  max_connections: 10, logger: Logger.new('log/db.log'))

Sequel also ships an IRB console, usually referred to as bin/sequel. The README's invocation is sequel sqlite://test.db, which opens an IRB session with the Sequel::Database object stored in DB. The README states that bin/sequel additionally supports migrating databases, dumping schema migrations and copying databases, and points to doc/bin_sequel.rdoc for those modes.

Where Sequel gets awkward: flexibility as a cost

The same design that makes Sequel adaptable makes it less opinionated than many Ruby developers expect. The README presents the DB constant as a convention, not a requirement, and explicitly notes that some frameworks using Sequel create the database instance for you, in which case Sequel::Model.db is the usual way to reach it. That is a hint that Sequel is often embedded inside something else, and the integration surface is not described in the README.

Connection details are another place where the library hands control back to you. The README warns that when you pass a hash instead of a URL, you must include the :adapter option. There is no validation layer described that catches a missing adapter before it fails. Similarly, the adapter list is long, but the README does not document which features work on which adapter. Prepared statements, savepoints, two-phase commit and sharding are listed as supported capabilities of the toolkit, not as a per-adapter matrix. If you rely on two-phase commit against a database that does not implement it well, the README gives you nothing to check against.

The README also does not document rollback behaviour, migration versioning semantics, or how the console's schema-dump mode handles destructive changes. Those are exactly the areas where an ORM's defaults usually protect you, and Sequel's documentation sends you to the RDoc site and doc/bin_sequel.rdoc instead. That is a reasonable structure for a mature library, but it means the README alone is not enough to plan a migration strategy.

Sequel compared with ActiveRecord's approach

The natural comparison in Ruby is ActiveRecord, which ships with Rails and assumes a model-first workflow. ActiveRecord's design centers on classes that inherit from a base model, with migrations, associations and validations generated by conventions. Sequel instead starts from the dataset and treats the ORM as an optional layer on top. The practical difference shows up in what you write first: an ActiveRecord developer defines a model and lets the framework derive the table, while a Sequel developer writes DB[:countries].where(region: 'Middle East') and gets a lazy, chainable, frozen query object back.

Sequel's README is explicit about capabilities that ActiveRecord historically handles differently or through additional gems: prepared statements, bound variables, savepoints, two-phase commit, transaction isolation, primary/replica configurations and database sharding are all listed as part of the toolkit. The dataset API also exposes map(:column) and as_hash(:key, :value), which return plain Ruby structures rather than model instances. For reporting code, ETL scripts or services that mostly move rows around, that is often the whole job.

The trade-off is ecosystem gravity. ActiveRecord is the default in Rails, so guides, gems and hiring expectations assume it. Sequel has a discussion forum on GitHub Discussions and an archived sequel-talk Google Group, and the README directs usage questions there rather than to the bug tracker. That is a clear support boundary: the issue tracker is for bugs in Sequel, not for help using it.

Maintenance, licence and the cost of upgrading

The repository is not archived, and its last push was on 2026-09-20, three days before this writing. On that evidence the project is being worked on now. The CHANGELOG file at the repository root is the place to look for release history, since the README itself carries no version number and no upgrade notes.

Sequel is MIT licensed, with MIT-LICENSE at the top level and the gemspec in the same directory. MIT is permissive: it allows commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are included. That is the general shape of the licence, not legal advice, and teams with unusual distribution models should read MIT-LICENSE directly.

The upgrade cost is harder to estimate from the README. There is no documented compatibility policy, no deprecation schedule and no list of breaking changes. The advanced features listed (two-phase commit, sharding, primary/replica) touch transaction and connection internals, and those are the areas most likely to change behaviour between versions. The CHANGELOG is the only source in the repository that would tell you, so pinning a version and reading it before each bump is the practical approach.

Editorial conclusion

Adopt Sequel when you want SQL to stay visible in Ruby code, when you need prepared statements, savepoints, two-phase commit or primary/replica setups, and when a layered DSL beats an object graph. Do not adopt it if your team wants an ActiveRecord-shaped API with migrations and associations handled by convention; Sequel's flexibility means you make more decisions yourself. Before committing, run gem install sequel and the sqlite:// example above to confirm your Ruby and sqlite3 build, then open bin/sequel against a real database and check that your adapter (MySQL, PostgreSQL, Oracle, JDBC, ODBC or one of the others listed in the README) connects and that the console's migration and schema-dump options behave against your schema.

Frequently asked questions

Official sources

1. Issues
2. jeremyevans/sequel on GitHub
3. License: MIT
4. Project website
5. README