Alpha

These pages are built from turborel-ruby’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Installing

This chapter tells what the driver needs, how a program takes the gem turborel in, and how it connects for the first time, with the standard API: the plain API, of connections, results and prepared statements, or the ActiveRecord adapter.

What the driver needs

  • Ruby 3.3 or later, on Linux, macOS or Windows; 3.3, 3.4 and 4.0 are tested.
  • No gem but Ruby's own: openssl, zlib and socket, which ship with Ruby, and bigdecimal, which the gem declares, as it is no longer a default gem from Ruby 3.4.
  • A Turborel server of the same release, which speaks protocol version 1 (running the server).
  • For the ActiveRecord adapter, ActiveRecord 8.1 or later, which a Rails application has already. The gem does not depend on it, and a program that does not use the adapter never loads it.

Taking the gem in

No package is published until every Turborel driver is done (VERSIONING.md); until then the driver is built from its source:

git clone https://github.com/turborel/turborel-ruby.git
cd turborel-ruby
bundle config set --local path vendor/bundle
bundle install
bundle exec rake build
gem install pkg/turborel-0.0.0.gem

or a program's Gemfile names the clone, as gem "turborel", path: "../turborel-ruby".

A first connection

require "turborel" loads the driver. Turborel.connect connects by a turborel:// URI, by settings by name, or both, and gives a Turborel::Connection; exec runs a statement and exec_params one with ? parameters, each giving a Turborel::Result. As Turborel's are, a connection's statements are in a transaction until COMMIT or ROLLBACK.

require "turborel"

conn = Turborel.connect("turborel://ann@127.0.0.1:7422/?tls_mode=disable")
conn.exec("CREATE TABLE GREETING (ID INTEGER PRIMARY KEY, WORDS VARCHAR(20))")
conn.exec_params("INSERT INTO GREETING VALUES (?, ?)", [1, "hello, Turborel"])
conn.exec("COMMIT")
conn.exec("SELECT ID, WORDS FROM GREETING").each { |row| puts "#{row["ID"]}: #{row["WORDS"]}" }
conn.close
1: hello, Turborel

Connecting tells every way to connect, and the low-level client, Turborel::Client, beneath the plain API, which has every feature of Turborel's own client library.

In a Rails application

The Gemfile names the gem, and config/database.yml the adapter turborel, with the connection's settings:

development:
  adapter: turborel
  host: db.example
  username: ann
  password: <%= ENV["TURBOREL_PASSWORD"] %>
  tls_mode: verify-full

or a URL, url: turborel://ann@db.example/. Requiring the gem registers the adapter, as Bundler requires it in a Rails application; a program outside Rails requires active_record/connection_adapters/turborel_adapter itself. The ActiveRecord Adapter tells what it does.