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.

The ActiveRecord Adapter

NAME

ActiveRecord::ConnectionAdapters::TurborelAdapter: the ActiveRecord adapter for Rails 8.1 and later, registered as turborel.

SYNOPSIS

# config/database.yml
production:
  adapter: turborel
  host: db.example
  port: 7422
  username: ann
  password: <%= ENV["TURBOREL_PASSWORD"] %>
  tls_mode: verify-full
  statement_limit: 1000
require "active_record"
require "active_record/connection_adapters/turborel_adapter"   # outside Rails
ActiveRecord::Base.establish_connection(adapter: "turborel", url: "turborel://ann@db.example/")

DESCRIPTION

The adapter is registered as turborel as the gem is required where ActiveRecord is loaded, as Bundler requires it in a Rails application, and as its own file is required. Its configuration's keys are the connection settings of Turborel::Client::Options, by the same names, username naming the user, or a url, a turborel:// URI; statement_limit bounds the statements kept prepared, 1000 by default. Each connection is a Turborel::Connection, its autocommit on outside a transaction.

Statements with bound values are prepared and executed, those ActiveRecord asks kept in the statement pool. A value is bound as Appendix A writes it: a time as a TIMESTAMP of its wall clock in ActiveRecord's default time zone, a date as a DATE, a time of day as a TIME, a decimal exactly. Bound to a ? mark, a value is cast to the mark's type, as ISO/IEC 9075:1992 §17.9 GR5 says, so a string longer than its column is cut to the column's length, the statement warning 01004; written as a literal, it fails as too long. A literal of a datetime is typed, DATE '2024-01-02', and of a binary string written X'00ff'. Names are written in double quotes, so a table or column is named in the case ActiveRecord gives it; SQL a program writes itself quotes them too, as where('"born" < ?', date).

A transaction begins as its first statement runs, autocommit off, and ends with COMMIT or ROLLBACK; a nested one is a savepoint; one of an isolation level begins with SET TRANSACTION. An identity column is the primary key ActiveRecord makes, BIGINT GENERATED BY DEFAULT AS IDENTITY, and the id of a record created is the value the INSERT generated. A query's LIMIT and OFFSET are written OFFSET n ROWS FETCH FIRST n ROWS ONLY.

The schema is read from INFORMATION_SCHEMA: tables, views, columns with their types, nullability and defaults, primary keys, indexes and foreign keys. A migration's ALTER TABLE takes one action each; a column or table is dropped RESTRICT, or CASCADE where force: :cascade asks; a unique index is a UNIQUE constraint, and renaming an index makes it again under the new name. change_column gives a column a longer or more precise type of its kind by SET DATA TYPE, then its default and nullability where asked; change_column_null sets or drops its NOT NULL, its nulls given the default first where one is given; and rename_table renames a table by RENAME TO, the indexes named after it too. A query locked, SELECT ... FOR UPDATE, fails, as the cursor of a direct query is read-only.

A result's column types are those the server declared, as the connection asks for them: an INTEGER column an integer, a NUMERIC(10,0) one a decimal of no scale, as select_all(...).column_types gives them.

The types, ActiveRecord's to Turborel's:

ActiveRecord Turborel
:primary_key BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY
:string CHARACTER VARYING, 32,767 characters unless a limit is given
:text CHARACTER LARGE OBJECT
:integer SMALLINT of limit 1 or 2, INTEGER, BIGINT of 5 to 8
:bigint BIGINT
:float DOUBLE PRECISION
:decimal DECIMAL, of its precision and scale
:datetime, :timestamp TIMESTAMP, of its precision
:time TIME, of its precision
:date DATE
:binary BINARY LARGE OBJECT
:boolean BOOLEAN
:json JSON

ERRORS

A failure is ActiveRecord's error, its cause the driver's Turborel::Error:

ActiveRecord's error The driver's failure
ConnectionNotEstablished A connection that could not be made; DatabaseConnectionError of a user refused, SQLSTATE 28000
ConnectionFailed Class 08, the connection lost
RecordNotUnique 23000, a PRIMARY KEY or UNIQUE constraint violated
InvalidForeignKey 23000, a FOREIGN KEY violated
NotNullViolation 23000, a NOT NULL column given none
ValueTooLong 22001
RangeError 22003
SerializationFailure 40001
TransactionRollbackError 40002, a commit that fails
QueryCanceled TB920, a statement cancelled
StatementInvalid Any other

EXAMPLES

require "active_record"
require "active_record/connection_adapters/turborel_adapter"

ActiveRecord::Base.establish_connection(adapter: "turborel", url: "turborel://ann@127.0.0.1:7422/?tls_mode=disable")
ActiveRecord::Migration.verbose = false
ActiveRecord::Schema.define do
  create_table :writers do |t|
    t.string :name, null: false, limit: 40
    t.date :born
    t.timestamps
  end
  create_table :works do |t|
    t.references :writer, foreign_key: true
    t.string :title, limit: 80
    t.index :title, unique: true
  end
end

class Writer < ActiveRecord::Base
  has_many :works
end

class Work < ActiveRecord::Base
  belongs_to :writer
end

ada = Writer.create!(name: "Ada Lovelace", born: Date.new(1815, 12, 10))
ada.works.create!(title: "Notes on the Analytical Engine")
ada.works.create!(title: "Letters")
p Writer.find(ada.id).born
p Work.where(writer: ada).order(:title).limit(1).pluck(:title)
begin
  ada.works.create!(title: "Letters")
rescue ActiveRecord::RecordNotUnique => e
  puts e.cause.sqlstate
end
p ActiveRecord::Base.lease_connection.indexes(:works).map { |index| [index.name, index.unique] }
Sun, 10 Dec 1815
["Letters"]
23000
[["index_works_on_writer_id", false], ["index_works_on_title", true]]

STANDARD

The driver's own, RULES.md D2, to ActiveRecord's adapter interface of Rails 8.1.

SEE ALSO

Turborel::Connection, Installing, Appendix A