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.