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.



559
560
561
 
# File 'lib/cloudflare_workers.rb', line 559

def initialize(js)
  @js = js
end

Instance Method Details

#exec(sql) ⇒ Object 



610
611
612
613
 
# File 'lib/cloudflare_workers.rb', line 610

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 and return all result rows as an Array of Hashes.

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)



571
572
573
574
575
 
# File 'lib/cloudflare_workers.rb', line 571

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 D1 exec result.



599
600
601
 
# File 'lib/cloudflare_workers.rb', line 599

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.

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



591
592
593
594
595
 
# File 'lib/cloudflare_workers.rb', line 591

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).

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



580
581
582
583
584
 
# File 'lib/cloudflare_workers.rb', line 580

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) —————



605
606
607
608
 
# File 'lib/cloudflare_workers.rb', line 605

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