Module: Cybertrain::DB

Defined in:
cybertrain/db.rb,
cybertrain/db/cli.rb,
cybertrain/db/blob.rb,
cybertrain/db/pool.rb,
cybertrain/db/error.rb,
cybertrain/db/migrator.rb,
cybertrain/db/connection.rb,
cybertrain/db/normalizer.rb,
cybertrain/db/sqlite_ddl.rb,
cybertrain/db/sqlite_ffi.rb,
cybertrain/db/schema_dumper.rb

Overview

SQLite access: the process-wide connection pool and its transactions.

Defined Under Namespace

Classes: Blob, Connection

Class Method Summary collapse

Class Method Details

.in_transaction? ⇒ Boolean

Whether the connection this thread’s DB.with would use has a transaction open: true inside a transaction block (or after a BEGIN run by hand in the same DB.with), false otherwise.

Returns:

  • (Boolean)

Raises:

  • (Cybertrain::DB::Error) —

    when not connected



74
75
76
# File 'cybertrain/db.rb', line 74

def self.in_transaction?
  with { |c| c.in_transaction? }
end

.transaction(immediate: false) {|conn| ... } ⇒ nil

Checks a connection out, opens a transaction on it (BEGIN, or BEGIN IMMEDIATE), yields the connection, COMMITs when the block returns and ROLLBACKs and re-raises when it raises; the connection goes back to the pool either way. Callable wherever with is, including from a controller action and from a method that also calls DB.with.

Cybertrain::DB.transaction(immediate: true) do |c| c.execute(“UPDATE accounts SET balance = balance - ? WHERE id = ?”, [amount, from_id]) c.execute(“UPDATE accounts SET balance = balance + ? WHERE id = ?”, [amount, to_id]) end

Everything on this thread that goes through DB.with while the block runs (Model#save, Relation queries) uses the transaction’s connection and so joins the transaction. A DB.transaction (or a c.begin! … c.commit! pair) nested in the block joins it as one more level, with the depth count of Connection#transaction: only the outermost level COMMITs, and a raise anywhere rolls the whole transaction back once it reaches the outermost block. There are no savepoints. A nested level raises Cybertrain::DB::Error when SQLite already rolled the transaction back on its own (SQLITE_FULL / IOERR / BUSY rescued inside the block). Not c.transaction { } on the block’s c: like DB.with’s, it is a boxed value under Spinel, and a yielding method cannot be called on one (spikes/NOTES.md rule 67).

immediate: true takes SQLite’s write lock at BEGIN: use it for a transaction that reads and then writes, so that a concurrent writer makes it wait at the start (SQLite’s busy handler, about five seconds) instead of failing with “database is locked” at its first write. It has no effect on a nested call. A thread started inside the block is not part of the transaction, and neither is a DB.with block that encloses the call: called from inside DB.with { |c| ... }, DB.transaction checks out a second connection (on a one-connection pool such as “:memory:” it then waits forever, as a nested DB.with does), so open the transaction first and do the work inside it.

Returns nil, not the block’s value (one generic return type does not type-check under Spinel): assign what the block computes to a local declared before it. Do not break or return out of the block (see Connection#transaction).

Parameters:

  • immediate (Boolean) (defaults to: false) —

    BEGIN IMMEDIATE instead of BEGIN

Yield Parameters:

Returns:

  • (nil)

Raises:

  • (Cybertrain::DB::Error) —

    when not connected, when BEGIN or COMMIT fails (the transaction is rolled back), or as above; and whatever the block raised, after the rollback



124
125
126
# File 'cybertrain/db.rb', line 124

def self.transaction(immediate: false, &block)
  run_transaction(immediate, block)
end