libsql-activerecord2

ActiveRecord adapter for libSQL / Turso, built on the libsql2 gem.

Installation

Add to your Gemfile:

gem "libsql-activerecord2"

Then run:

bundle install

Configuration

Configure the libsql adapter in config/database.yml (Rails) or via ActiveRecord::Base.establish_connection.

Local File

development:
  adapter: libsql
  database: db/development.sqlite3

In-Memory

test:
  adapter: libsql
  database: ":memory:"

Remote (Turso)

production:
  adapter: libsql
  database: libsql://your-db.turso.io
  token: <%= ENV["TURSO_AUTH_TOKEN"] %>

Embedded Replica

Keeps a local replica that syncs with the remote database — ideal for read-heavy workloads with low latency.

production:
  adapter: libsql
  database: libsql://your-db.turso.io
  token: <%= ENV["TURSO_AUTH_TOKEN"] %>
  replica_path: db/local_replica.sqlite3
  read_your_writes: true  # default: true

To manually trigger a sync:

ActiveRecord::Base.connection.sync

Usage

Once configured, use ActiveRecord as usual:

class User < ApplicationRecord
end

User.create!(name: "Alice", email: "alice@example.com")
User.where(name: "Alice").first

Without Rails

require "libsql_activerecord"

ActiveRecord::Base.establish_connection(
  adapter: "libsql",
  database: ":memory:"
)

Supported Features

Feature	Status
Migrations	Yes
Primary keys	Yes
Savepoints (nested transactions)	Yes
Foreign keys	Yes
JSON columns	Yes
DDL transactions	No (planned)
EXPLAIN	No (planned)
Prepared statement cache	No (planned)
INSERT RETURNING	No (planned)

Connection Modes

Mode	Supported
Local file	Yes
In-memory	Yes
Remote (Turso)	Yes
Embedded replica	Yes

Type Mapping

ActiveRecord Type	SQL Type	SQLite Affinity
:primary_key	INTEGER PRIMARY KEY AUTOINCREMENT	INTEGER
:string / :text	TEXT	TEXT
:integer	INTEGER	INTEGER
:float / :decimal	REAL	REAL
:datetime / :timestamp	DATETIME	NUMERIC
:date	DATE	NUMERIC
:time	TIME	NUMERIC
:binary	BLOB	BLOB
:boolean	BOOLEAN	NUMERIC
:json	TEXT	TEXT

Exception Mapping

libSQL Error	ActiveRecord Exception
NOT NULL constraint failed	ActiveRecord::NotNullViolation
UNIQUE constraint failed	ActiveRecord::RecordNotUnique
FOREIGN KEY constraint failed	ActiveRecord::InvalidForeignKey
Other Libsql::Error	ActiveRecord::StatementInvalid

Fork Safety

The adapter supports forking web servers (Puma, Unicorn). The discard! method cleans up the Rust runtime safely, and new connections are established in child processes automatically.

Requirements

• Ruby >= 3.4
• ActiveRecord >= 8.0
• libsql2 >= 0.1.5

Development

bundle install
bundle exec rspec              # Unit tests

# Integration tests (per AR version)
cd integration_tests/8.0 && bundle install && bundle exec rspec
cd integration_tests/8.1 && bundle install && bundle exec rspec

License

Released under the MIT License.