Class: Cloudflare::D1Database

Inherits:
Object
  • Object
show all
Defined in:
lib/cloudflare_workers.rb

Overview

D1Database wraps a Cloudflare D1 JS binding. The public API is modelled on CRuby’s ‘sqlite3-ruby` gem (`SQLite3::Database`) so that the calling code reads identically:

# sqlite3-ruby on CRuby:
rows = db.execute("SELECT * FROM users WHERE id = ?", [1])

# homura on Opal (+ async):
rows = db.execute("SELECT * FROM users WHERE id = ?", [1]).__await__

Every query method returns a JS Promise. Use ‘.__await__` inside a `# await: true` route block to unwrap it synchronously (Opal compiles `.__await__` to a native JS `await`).

Results are always Hashes — ‘results_as_hash` is effectively hardcoded to `true`. This matches the common `db.results_as_hash = true` convention in the sqlite3-ruby world and gives downstream ORM code a ready-made Hash-per-row interface to build on.

Instance Method Summary collapse

Constructor Details

#initialize(js) ⇒ D1Database

Returns a new instance of D1Database.



603
604
605
 
# File 'lib/cloudflare_workers.rb', line 603

def initialize(js)
  @js = js
end

Instance Method Details

#exec(sql) ⇒ Object 



658
659
660
661
 
# File 'lib/cloudflare_workers.rb', line 658

def exec(sql)
  js = @js
  `(#{js}.exec ? #{js}.exec(#{sql}) : #{js}.prepare(#{sql}).run())`
end

#execute(sql, bind_params = []) ⇒ Object

Execute a SQL statement with optional bind parameters. Returns a JS Promise resolving to an Array of Hashes; the build-time auto-await pass rewrites the usual Sinatra call sites so app code can stay ‘db.execute(…)` instead of spelling `.__await__`.

db.execute("SELECT * FROM users")                           → Array<Hash>
db.execute("SELECT * FROM users WHERE id = ?", [1])         → Array<Hash>
db.execute("INSERT INTO users (name) VALUES (?)", ["alice"]) → Array<Hash> (empty for writes)



617
618
619
620
621
 
# File 'lib/cloudflare_workers.rb', line 617

def execute(sql, bind_params = [])
  stmt = prepare(sql)
  stmt = stmt.bind(*bind_params) unless bind_params.empty?
  stmt.all
end

#execute_batch(sql) ⇒ Object

Execute one or more raw SQL statements separated by semicolons. Useful for schema migrations. Returns the raw async D1 exec result.



647
648
649
 
# File 'lib/cloudflare_workers.rb', line 647

def execute_batch(sql)
  exec(sql)
end

#execute_insert(sql, bind_params = []) ⇒ Object

Execute a write statement (INSERT / UPDATE / DELETE) and return a metadata Hash with ‘changes`, `last_row_id`, `duration`, etc. Returns a JS Promise resolving to that metadata Hash.

meta = db.execute_insert("INSERT INTO users (name) VALUES (?)", ["alice"])
meta['last_row_id']  # → 7



639
640
641
642
643
 
# File 'lib/cloudflare_workers.rb', line 639

def execute_insert(sql, bind_params = [])
  stmt = prepare(sql)
  stmt = stmt.bind(*bind_params) unless bind_params.empty?
  stmt.run
end

#get_first_row(sql, bind_params = []) ⇒ Object

Execute and return only the first row (or nil). Returns a JS Promise resolving to a Hash or nil.

db.get_first_row("SELECT * FROM users WHERE id = ?", [1])  → Hash or nil



627
628
629
630
631
 
# File 'lib/cloudflare_workers.rb', line 627

def get_first_row(sql, bind_params = [])
  stmt = prepare(sql)
  stmt = stmt.bind(*bind_params) unless bind_params.empty?
  stmt.first
end

#prepare(sql) ⇒ Object

—- low-level D1 API (prepare/bind/all/first/run) —————



653
654
655
656
 
# File 'lib/cloudflare_workers.rb', line 653

def prepare(sql)
  js = @js
  D1Statement.new(`#{js}.prepare(#{sql})`)
end