Turso Quickstart (ActiveRecord)

This is currently in technical preview. Join us in Discord to report any issues.

In this Ruby quickstart we will learn how to:

Retrieve database credentials
Install the libSQL ActiveRecord gem
Connect to a local or remote Turso database
Define and create models
Perform basic CRUD operations
Execute raw SQL queries
Work with migrations

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.Get the database URL:

turso db show --url <database-name>

Get the database authentication token:

turso db tokens create <database-name>

Assign credentials to the environment variables inside .env.

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

Install

In your Ruby project, add the following gems to your Gemfile:

gem 'libsql_activerecord'
gem 'activerecord'

Then run:

bundle install

Connect

Create a Ruby file (e.g., database.rb) to set up the database connection:

Embedded Replicas

require 'libsql_activerecord'
require 'active_record'

ActiveRecord::Base.establish_connection(
  adapter: 'libsql',
  url: ENV['TURSO_DATABASE_URL'],
  auth_token: ENV['TURSO_AUTH_TOKEN'],
  path: 'path/to/local/replica.db'
)

Local only

require 'libsql_activerecord'
require 'active_record'

ActiveRecord::Base.establish_connection(
  adapter: 'libsql',
  path: 'path/to/local.db'
)

Remote only

require 'libsql_activerecord'
require 'active_record'

ActiveRecord::Base.establish_connection(
  adapter: 'libsql',
  url: ENV['TURSO_DATABASE_URL'],
  auth_token: ENV['TURSO_AUTH_TOKEN']
)

In-memory

require 'libsql_activerecord'
require 'active_record'

ActiveRecord::Base.establish_connection(adapter: 'libsql')

Define models

Create model files for your database tables. For example, product.rb:

class Product < ActiveRecord::Base
  validates :name, presence: true
end

Create and execute a migration

Create a migration file (e.g., 001_create_products.rb):

class CreateProducts < ActiveRecord::Migration[8.0]
  def change
    create_table :products do |t|
      t.string :name
      t.text :description
      t.timestamps
    end
  end
end

Execute the migration:

require_relative 'database'
require_relative '001_create_products'

CreateProducts.migrate(:up)

Execute

Perform some basic CRUD operations:

product = Product.create(name: 'Book', description: 'A book about books')

all_products = Product.all
first_product = Product.first
found_product = Product.find_by(name: 'Book')

product.update(description: 'An updated description')

product.destroy

results = ActiveRecord::Base.connection.execute("SELECT * FROM products WHERE name LIKE '%Book%'")

results.each do |row|
  puts row.inspect
end

Work with associations

Define associations in your models:

class Author < ActiveRecord::Base
  has_many :books
end

class Book < ActiveRecord::Base
  belongs_to :author
end

Use associations in your code:

author = Author.create(name: 'Jane Doe')
book = author.books.create(title: 'My First Book')

puts author.books.count # => 1
puts book.author.name # => "Jane Doe"

Turso Cloud

SDKs

CLI

API Reference

Integrations

Turso Quickstart (ActiveRecord)