ruflet_record 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ff4208c2b7a87dc5551191990f98dfcae70e0fb269eb3a2dbb17f15c37486ee
+  data.tar.gz: 97605cab4d6d1ed79775b33ec3628f1264c857b8be05cc69bd8e95d8e870adb5
+SHA512:
+  metadata.gz: b654171b28b24b46383be6fcbc5194271f6ee573413cb973c3d6dd9842e9c6e18bc84f3a82d8f1b2fbd000375562b2e3904ea5cded0a3f11a37b05527ebe44ea
+  data.tar.gz: 2e6e410915adb49b2a8d06b66e6e064bb8676c28473a2301cafa35142e1c94140dfdff6b75bbc3b83549ae099a2289937a071466bd6aa4b9bda9da56dfc18639

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruflet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,173 @@
+# RufletRecord
+
+RufletRecord is a small, lazy SQLite ORM for Ruflet applications. Its API is
+shaped like the useful core of Active Record, but it has no Rails or
+ActiveSupport dependency and is compiled directly into Ruflet's mruby VM.
+
+The gem runs on CRuby with the `sqlite3` gem and on Ruflet's mruby runtime with
+the bundled native SQLite 3.53.4 bridge.
+
+## Setup
+
+```ruby
+require "ruflet_record"
+
+RufletRecord.establish_connection(
+  database: File.join(Dir.pwd, "storage", "app.sqlite3"),
+  journal_mode: :wal,
+  timeout: 5_000
+)
+```
+
+`foreign_keys` defaults to `true`. Use `database: ":memory:"` in tests.
+
+## Schema
+
+```ruby
+RufletRecord::Schema.define do
+  create_table :users, if_not_exists: true do |table|
+    table.string :name, null: false
+    table.string :email
+    table.boolean :active, default: true
+    table.timestamps
+    table.index :email, unique: true
+  end
+
+  create_table :posts, if_not_exists: true do |table|
+    table.references :user, null: false, foreign_key: { on_delete: :cascade }
+    table.string :title, null: false
+    table.text :body
+    table.timestamps
+  end
+end
+```
+
+Supported column helpers are `string`, `text`, `integer`, `float`, `decimal`,
+`boolean`, `datetime`, `date`, `binary`, `json`, `references`, and
+`timestamps`. Schema operations include `create_table`, `drop_table`,
+`add_column`, `add_index`, `remove_index`, and `rename_table`.
+
+`references` creates an index by default. Pass `index: false` to omit it and
+`foreign_key: true` to reference the conventionally named table. A hash can
+configure `to_table`, `primary_key`, `on_delete`, and `on_update`; supported
+actions are `cascade`, `restrict`, `set_null`, `set_default`, and `no_action`.
+
+For application migration classes:
+
+```ruby
+class CreateTasks < RufletRecord::Migration
+  def change
+    create_table :tasks do |table|
+      table.string :title, null: false
+      table.boolean :done, default: false
+      table.timestamps
+    end
+  end
+end
+
+CreateTasks.migrate(:up)
+```
+
+## Models
+
+```ruby
+class User < RufletRecord::Base
+  validates_presence_of :name
+  validates_uniqueness_of :email
+
+  has_many :posts
+  has_one :profile
+
+  scope :active, -> { where(active: true) }
+end
+
+class Post < RufletRecord::Base
+  belongs_to :user
+end
+```
+
+Table names are inferred (`Post` → `posts`). Override conventions where
+needed:
+
+```ruby
+class LegacyEntry < RufletRecord::Base
+  self.table_name = "entries"
+  self.primary_key = "entry_id"
+end
+```
+
+## Persistence
+
+```ruby
+user = User.create!(name: "Ada", email: "ada@example.com")
+post = user.posts.create!(title: "Notes")
+
+user.update!(active: false)
+user.reload
+user.destroy
+```
+
+The common persistence API includes `new`, `create`, `create!`, `save`,
+`save!`, `update`, `update!`, `update_columns`, `touch`, `destroy`, `delete`,
+`reload`, `find_or_initialize_by`, `find_or_create_by`, and
+`find_or_create_by!`.
+
+## Lazy queries
+
+Building a relation never touches SQLite:
+
+```ruby
+query = User.where(active: true).order(name: :asc).limit(20)
+# No SQL has run yet.
+
+users = query.to_a # SQL runs here.
+```
+
+These methods only build immutable relation objects:
+
+- `where` and `where.not`
+- `order` and `reorder`
+- `select` and `distinct`
+- `limit` and `offset`
+- `joins`
+- model scopes and association readers
+
+SQL executes when records or scalar values are requested with `each`, `to_a`,
+`first`, `last`, `find`, `find_by`, `pluck`, `pick`, `ids`, `count`, `sum`,
+`average`, `minimum`, `maximum`, or `exists?`. Writes execute immediately.
+
+```ruby
+User.where("age >= ?", 18)
+User.where(id: [1, 2, 3])
+User.where(created_at: start_time..end_time)
+User.where.not(active: false)
+User.order(age: :desc).pluck(:name, :age)
+```
+
+Values use SQLite bind parameters. Identifiers are quoted. Raw ordering is
+strictly validated; use `RufletRecord.sql(...)` only for trusted application
+SQL:
+
+```ruby
+User.select(RufletRecord.sql("COUNT(*) AS total"))
+```
+
+## Transactions
+
+```ruby
+User.transaction do
+  user = User.create!(name: "Grace")
+  user.posts.create!(title: "Compiler notes")
+end
+```
+
+Nested transactions use SQLite savepoints.
+
+## Deliberate limits
+
+RufletRecord is not Rails Active Record. It deliberately omits callbacks,
+STI, eager loading, polymorphic associations, database portability, and Arel.
+Hard invariants should use SQLite constraints and unique indexes; the included
+presence and uniqueness validations exist for user-facing errors.
+
+For uncommon SQL, use `RufletRecord.connection.execute(sql, binds)` directly.

data/lib/ruflet_record/adapters/sqlite_adapter.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module RufletRecord
+  module Adapters
+    class SQLiteAdapter
+      attr_reader :database
+
+      def initialize(config)
+        @config = normalize_config(config)
+        @database = @config[:database]
+        @driver = build_driver(@database)
+        @transaction_depth = 0
+        configure
+      end
+
+      def execute(sql, binds = [])
+        @driver.execute(sql, normalize_binds(binds))
+      rescue StandardError => error
+        raise StatementInvalid, error.message
+      end
+
+      def execute_batch(sql)
+        @driver.execute_batch(sql)
+      rescue StandardError => error
+        raise StatementInvalid, error.message
+      end
+
+      def select_all(sql, binds = [])
+        execute(sql, binds)
+      end
+
+      def select_one(sql, binds = [])
+        select_all(sql, binds).first
+      end
+
+      def select_value(sql, binds = [])
+        row = select_one(sql, binds)
+        row && row.values.first
+      end
+
+      def insert(sql, binds = [])
+        execute(sql, binds)
+        @driver.last_insert_row_id
+      end
+
+      def update(sql, binds = [])
+        execute(sql, binds)
+        @driver.changes
+      end
+      alias delete update
+
+      def transaction
+        savepoint = "ruflet_record_#{@transaction_depth}"
+        if @transaction_depth.zero?
+          execute("BEGIN IMMEDIATE")
+        else
+          execute("SAVEPOINT #{SQL.quote_identifier(savepoint)}")
+        end
+        @transaction_depth += 1
+        result = yield
+        @transaction_depth -= 1
+        if @transaction_depth.zero?
+          execute("COMMIT")
+        else
+          execute("RELEASE SAVEPOINT #{SQL.quote_identifier(savepoint)}")
+        end
+        result
+      rescue Exception
+        @transaction_depth -= 1 if @transaction_depth > 0
+        if @transaction_depth.zero?
+          execute("ROLLBACK")
+        else
+          execute("ROLLBACK TO SAVEPOINT #{SQL.quote_identifier(savepoint)}")
+          execute("RELEASE SAVEPOINT #{SQL.quote_identifier(savepoint)}")
+        end
+        raise
+      end
+
+      def table_exists?(name)
+        !select_value("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1", [name.to_s]).nil?
+      end
+
+      def columns(table_name)
+        select_all("PRAGMA table_info(#{SQL.quote_identifier(table_name)})").map do |row|
+          Column.new(
+            row["name"], row["type"], row["notnull"].to_i == 1,
+            row["dflt_value"], row["pk"].to_i == 1
+          )
+        end
+      end
+
+      def indexes(table_name)
+        select_all("PRAGMA index_list(#{SQL.quote_identifier(table_name)})")
+      end
+
+      def close
+        @driver.close
+      end
+
+      private
+
+      def normalize_config(config)
+        value = config.is_a?(Hash) ? config.dup : { database: config }
+        value = value.each_with_object({}) { |(key, item), result| result[key.to_sym] = item }
+        database = value[:database]
+        raise ArgumentError, "database is required" if database.nil? || database.to_s.empty?
+        value[:database] = database.to_s
+        value
+      end
+
+      def build_driver(path)
+        if RufletRecord.const_defined?(:NativeSQLite)
+          NativeDriver.new(path)
+        else
+          CRubyDriver.new(path)
+        end
+      end
+
+      def configure
+        execute("PRAGMA foreign_keys = ON") if @config.fetch(:foreign_keys, true)
+        timeout = @config.fetch(:timeout, 5_000).to_i
+        execute("PRAGMA busy_timeout = #{timeout}")
+        if @config[:journal_mode]
+          mode = @config[:journal_mode].to_s.upcase
+          raise ArgumentError, "invalid journal mode" unless %w[DELETE TRUNCATE PERSIST MEMORY WAL OFF].include?(mode)
+          execute("PRAGMA journal_mode = #{mode}")
+        end
+      end
+
+      def normalize_binds(binds)
+        binds.map do |value|
+          if value == true
+            1
+          elsif value == false
+            0
+          elsif value.is_a?(Time)
+            "%04d-%02d-%02d %02d:%02d:%02d" % [
+              value.year, value.month, value.day,
+              value.hour, value.min, value.sec
+            ]
+          else
+            value
+          end
+        end
+      end
+    end
+
+    class NativeDriver
+      def initialize(path)
+        @database = RufletRecord::NativeSQLite::Database.new(path)
+      end
+
+      def execute(sql, binds)
+        @database.execute(sql, binds)
+      end
+
+      def execute_batch(sql)
+        @database.execute_batch(sql)
+      end
+
+      def changes
+        @database.changes
+      end
+
+      def last_insert_row_id
+        @database.last_insert_row_id
+      end
+
+      def close
+        @database.close
+      end
+    end
+
+    unless RUBY_ENGINE == "mruby"
+      require "sqlite3"
+
+      class CRubyDriver
+        def initialize(path)
+          @database = SQLite3::Database.new(path)
+          @database.results_as_hash = true
+        end
+
+        def execute(sql, binds)
+          @database.execute(sql, binds).map do |row|
+            normalized = {}
+            row.each { |key, value| normalized[key.to_s] = value unless key.is_a?(Integer) }
+            normalized
+          end
+        end
+
+        def execute_batch(sql)
+          @database.execute_batch(sql)
+          []
+        end
+
+        def changes
+          @database.changes
+        end
+
+        def last_insert_row_id
+          @database.last_insert_row_id
+        end
+
+        def close
+          @database.close
+        end
+      end
+    end
+  end
+end