libsql-sequel 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37c836e635f6104c6972774e8cb3dba6397cfbf5b6c958c19f15eaaca4fc1367
+  data.tar.gz: adce3fe4850eab4d30b4b303f404520f969390060dded1b89def96675d2f7249
+SHA512:
+  metadata.gz: d02c3ee895aa85b2e4bae54743d0fc8b8b0028a8170b9b87212caeab594798b080c52dba582b2fd882a19e23a3aea5989ba5f0b53dc33ba68f7c924cb544b606
+  data.tar.gz: 8c777ebc4996b0d96a5e4fd437337347568820f5a8a3adc2569ce69ad603f6b133acb386e6f8c2e59a641789b62f7c8aef780e66234908ba05e28e394276df37

data/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Francesco Canessa
+
+Adapter conventions and portions adapted from Sequel:
+Copyright (c) 2007-2008 Sharon Rosner
+Copyright (c) 2008-2026 Jeremy Evans and contributors
+
+Native API integration informed by libsql-ruby:
+Copyright (c) 2024 Turso (libSQL)
+
+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,144 @@
+# libsql-sequel
+
+A modular Ruby adapter for using [Sequel](https://github.com/jeremyevans/sequel) with local libSQL databases, remote Turso databases, and embedded replicas through [libsql-ruby](https://github.com/tursodatabase/libsql-ruby).
+
+```ruby
+require 'libsql-sequel'
+
+DB = Sequel.connect(
+  adapter: :libsql,
+  database: ENV.fetch('TURSO_DATABASE_URL'),
+  auth_token: ENV.fetch('TURSO_AUTH_TOKEN')
+)
+
+DB.create_table?(:items) do
+  primary_key :id
+  String :name, null: false
+  Integer :quantity, default: 0
+end
+
+id = DB[:items].insert(name: 'Hello, Turso', quantity: 3)
+DB[:items].where(id: id).first
+# => {id: 1, name: "Hello, Turso", quantity: 3}
+
+DB.disconnect
+```
+
+## Installation
+
+Install from [RubyGems](https://rubygems.org/gems/libsql-sequel):
+
+```ruby
+# Gemfile
+gem 'libsql-sequel', '~> 0.3.0'
+```
+
+Then run `bundle install`. To install without Bundler:
+
+```sh
+gem install libsql-sequel -v 0.3.0
+```
+
+Ruby 3.3+ and Sequel 5.80–5.x are required. The native dependency is **pinned to `turso_libsql` 0.2.0**: 0.2.1 contains native debug output of connection credentials and SQL. Do not widen that dependency without reviewing the replacement library. The adapter uses the bundled native library with scoped corrections for the driver's Ruby wrapper; it does not patch global `Libsql` classes or require `sqlite3` at runtime.
+
+The driver bundles Apple Silicon macOS and glibc Linux x86_64/aarch64 libraries. Intel macOS, Windows, musl Linux, and JRuby are not supported by this pinned distribution. Current verification was on Apple Silicon macOS / Ruby 4.0.5. See [compatibility and verification](docs/compatibility.md).
+
+## Connection modes
+
+Turso Cloud's `turso://` URLs are also accepted, both as `database:`/`url:`
+options and directly through `Sequel.connect('turso://...', auth_token: ...)`.
+They are normalized to `https://` for the pinned native driver before opening
+a connection. The same credential/query/fragment validation applies. A
+`turso://` database URL is never treated as a local file path.
+
+```ruby
+# Memory: a single pooled connection.
+db = Sequel.connect(adapter: :libsql)
+
+# Local file: regular Sequel pooling (default four connections).
+db = Sequel.connect(adapter: :libsql, database: 'app.db', max_connections: 4)
+
+# Native libsql:// URLs work directly. https:// and http:// use the hash form.
+db = Sequel.connect(ENV.fetch('TURSO_DATABASE_URL'),
+  auth_token: ENV.fetch('TURSO_AUTH_TOKEN'))
+
+# Embedded replica: local file plus remote primary URL.
+db = Sequel.connect(
+  adapter: :libsql,
+  database: ENV.fetch('TURSO_DATABASE_URL'),
+  path: 'replica.db',
+  auth_token: ENV.fetch('TURSO_AUTH_TOKEN'),
+  sync_interval: 1_000,
+  read_your_writes: true
+)
+db.sync # => {frame_no: ..., frames_synced: ...}
+```
+
+`url:` can also specify the remote URL; `database:` or `path:` then names the local replica. Memory databases and replicas require `max_connections: 1`. This avoids separate memory databases and multiple replication workers targeting one file. Replica sync cannot run inside a transaction. Embedded replication is implemented but has not been tested against a live Turso primary.
+
+Keep tokens in the `auth_token:` option rather than the URL. URLs with credentials, query parameters, or fragments are rejected.
+
+For Puma and other forking servers, initialize native connections inside each worker after forking. If the parent has opened connections, call `DB.disconnect` in `before_fork` to release them in their owning process. Calling `DB.disconnect` in a child quietly discards inherited handles without invoking native destructors; inherited queries still raise `Sequel::Error`. Disconnecting does not reset an already initialized Rust runtime, so child cleanup alone does not make preloading the native runtime safe.
+
+Local connections enable foreign keys, case-sensitive `LIKE`, and a 5,000 ms SQLite busy timeout by default. `timeout:`, `case_sensitive_like:`, `auto_vacuum:`, `synchronous:`, and `temp_store:` are local-only options. The native remote parser rejects those PRAGMAs; remote connections keep the server's `LIKE` behavior. `timeout:` is a SQLite lock timeout, not an HTTP timeout. `readonly:`, custom regexp functions, `disable_dqs:`, offline-write mode, and custom TLS options are unsupported and rejected.
+
+## Sequel features
+
+SQL generation, schema introspection, migrations, models, associations, upserts, and `RETURNING` reuse Sequel's shared SQLite implementation. The adapter scheme is `:libsql`; `database_type` is `:sqlite`.
+
+```ruby
+DB.transaction do
+  DB[:items].insert(name: 'committed')
+  DB.transaction(savepoint: true) do
+    DB[:items].insert(name: 'rolled back')
+    raise Sequel::Rollback
+  end
+end
+
+find_item = DB[:items].where(id: :$id).prepare(:first, :find_item)
+find_item.call(id: 1)
+DB.call(:find_item, id: 1)
+
+DB[:items].where(id: :$id).call(:update, {id: 1, quantity: 5}, quantity: :$quantity)
+DB[:items].returning(:id).insert(name: 'returned')
+```
+
+Bound values use native parameters. Named Sequel prepared queries prepare a native statement for each execution and always release it; there is no persistent statement cache. `DB.run` supports SQL batches. Commit and rollback run as SQL so errors propagate to Sequel instead of using the driver's abort-prone native transaction helpers. There are no automatic retries of failed writes.
+
+## Values and result types
+
+Integers preserve signed 64-bit values; strings are converted to UTF-8; blobs preserve all bytes. Use `Sequel.blob(bytes)` for binary data. Invalid text encodings and strings that cannot be converted to UTF-8 raise `Sequel::Error`. NUL-containing text is rejected on input because the native C API truncates it. The same upstream limitation affects existing TEXT values containing NUL when reading them; store those values as blobs. Out-of-range bound integers, invalid text, and non-finite bound floats are rejected.
+
+The native API does not expose declared result-column types. Simple single-table datasets infer date, datetime, time, decimal, and boolean conversions from Sequel's schema cache, including direct column aliases and prepared queries. Raw SQL, joins, CTEs, compounds, and arbitrary expressions retain native SQLite values. Use explicit hints when necessary:
+
+```ruby
+DB.fetch('SELECT active, created_at FROM items').with_libsql_types(
+  active: :boolean,
+  created_at: :datetime
+).all
+
+# Supported hints: :boolean, :date, :datetime, :timestamp, :time, :decimal,
+# :integer, :float, :blob, or a callable. NULL always remains nil.
+DB.fetch('SELECT upper(name) AS label FROM items').with_libsql_types(
+  label: ->(value) { value.freeze }
+).all
+```
+
+Use `Sequel::Model` normally for single-table model datasets. Joined/eager-graph results with boolean or temporal columns may need explicit result type hints. Expression aliases never acquire a type merely because they match a table column name. SQLite's own numeric affinity and decimal precision limitations still apply.
+
+## Development and tests
+
+```sh
+bundle install
+bundle exec rake check         # syntax, visibility, and warning-enabled tests
+bundle exec rake lint          # syntax and method visibility only
+bundle exec rake test          # real native local/file databases
+bundle exec rake upstream      # upstream SQLite + integration specs
+bundle exec rake remote_local  # real native HTTP client, local Hrana server
+```
+
+`upstream` and `remote_local` need the ignored reference checkouts; setup instructions are in [development.md](docs/development.md). `rake` defaults to `check`. Checks follow Sequel's own syntax/warnings/visibility approach; Sequel does not configure RuboCop or a complexity analyzer. See [the spec and code-quality review](docs/testing-review.md).
+
+For an explicit test against a **disposable** hosted database, set `LIBSQL_TEST_URL` and `LIBSQL_TEST_AUTH_TOKEN` in your environment, then run `bundle exec rake remote`. It creates randomly named test tables and drops those tables afterward. Hosted authentication and HTTPS remote operations have been validated with a `turso://` URL; embedded replication remains unverified. See [compatibility and verification](docs/compatibility.md) for the tested scope.
+
+See [architecture](docs/architecture.md), [compatibility](docs/compatibility.md), and [the local example](examples/local.rb).

data/docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+The adapter follows Sequel's small Database/Dataset adapter pattern and delegates SQL dialect behavior to `Sequel::SQLite::DatabaseMethods` and `DatasetMethods`. It does not subclass the sqlite3-backed adapter, avoiding a second native database driver in production.
+
+| Component | Responsibility |
+| --- | --- |
+| `lib/sequel/adapters/libsql.rb` | Register `:libsql`, create pooled connections, execute/log SQL, map errors, bind Ruby values, expose replica sync |
+| `lib/sequel/libsql/configuration.rb` | Normalize memory/file/remote/replica options, reject unsupported or conflicting configuration |
+| `lib/sequel/libsql/connection.rb` | Own database/connection handles; scope statements, results, and rows with `ensure` |
+| `lib/sequel/libsql/native.rb` | Use the driver's native library/ABI; correct error, string, blob, and signed-integer handling |
+| `lib/sequel/libsql/dataset.rb` | Map native rows to Sequel hashes, bind query parameters, and quote text |
+| `lib/sequel/libsql/result_types.rb` | Resolve column origins and explicit type hints; reject ambiguous inference |
+| `lib/sequel/libsql/type_converter.rb` | Convert storage values to semantic SQLite types |
+
+## Ownership and concurrency
+
+Each Sequel pool slot owns one native Database and Connection. A query owns its Statement, Result, and one Row at a time. Values are copied into Ruby before the row is freed. Native strings/blobs returned by the C API are copied and freed exactly once. Cleanup runs in reverse order on success, errors, early iteration exit, and connection setup failure. A result retained after its block raises rather than touching freed native memory.
+
+Potentially blocking initialization, prepare, execute, query, row advance, and sync calls release the Ruby GVL. Sequel serializes access to a given connection; independent pool slots can run concurrently. Memory and embedded-replica pools are restricted to one slot. In the owning process, explicit `disconnect` closes both handles, is idempotent, and leaves Sequel able to reconnect lazily.
+
+There are no finalizers: explicit ownership avoids GC freeing a native parent while a child is in use. Application code must disconnect databases it no longer needs. Connections detect queries from a different process and reject them. In a child, `disconnect` only clears inherited references, allowing Sequel to empty its pool without calling unsafe native destructors or affecting the parent's connections. Release parent connections in `before_fork`. The upstream Rust runtime must be initialized in each worker after fork; disconnecting does not reset it, and this is not a fork-safe driver.
+
+## Transactions and prepared queries
+
+Sequel reserves one pool connection for the transaction and issues SQL BEGIN, COMMIT, ROLLBACK, and SAVEPOINT commands. The driver's native Transaction object is deliberately unused because its commit/rollback C functions return void and unwrap errors. SQL errors instead pass through a typed `Native::Error`, then Sequel's error classification.
+
+Sequel's unnumbered argument mapper generates `?` placeholders and orders/repeats values correctly. Both `.call` and named `.prepare` queries use native binding. Native statements are short-lived, so failed statements cannot leave stale bindings, and DDL never needs to clear a statement cache. This trades additional prepare work (including remote round trips) for predictable resource handling.
+
+## Type information
+
+The C API exposes runtime types and column names, but not column declarations/origins. General sqlite3-style automatic result conversion is therefore impossible without a new upstream API. This adapter resolves only known single-table column projections, consulting Sequel's schema cache after the SQL has successfully prepared. It leaves expressions and ambiguous projections unchanged and offers `with_libsql_types` for explicit conversions.
+
+Sequel's cached placeholder literalizer optimization is disabled because it replaces projected columns with opaque arguments. Without native declared-type metadata, that made repeated `get` calls lose their conversions after the cache activated. Native bound variables and named prepared statements remain supported; the tradeoff is additional Ruby SQL generation work.
+
+Numeric timestamps follow Sequel's SQLite convention: Integer means Unix seconds and Float means Julian day. Numeric TIME values preserve microseconds. BLOB columns containing integer/real/text storage values convert through their string representation, and nonnumeric text in a decimal column remains text, matching Sequel's SQLite adapter.
+
+Sequel invalidates its own schema cache for schema DSL changes. External schema changes and arbitrary DDL via `run` follow Sequel's usual cache rules; reload the affected schema or reconnect the Database object when needed. No extra unbounded type cache is introduced.
+
+## Driver boundary
+
+The compatibility layer uses `turso_libsql`'s shipped structs and binary functions without altering `Libsql` or `CLibsql` globally. Error messages are copied before freeing their C allocation. Signed integers are recovered from the upstream unsigned declaration. Blob binding is checked before String binding, and text uses UTF-8 byte lengths with a retained input pointer. Slice release uses the correct ABI type. Descriptor strings remain retained for their native database lifetime.
+
+The exact 0.2.0 dependency prevents accidental activation of the credential-logging 0.2.1 native release. A future driver upgrade needs local/HTTP contract tests plus native binary review, not just a version bump.

data/docs/compatibility.md

@@ -0,0 +1,38 @@
+# Compatibility and verification
+
+## Verified in this workspace
+
+As of 2026-10-31, Apple Silicon macOS, Ruby 4.0.5, `turso_libsql` 0.2.0, bundled SQLite 3.45.1:
+
+- Native local/file tests cover CRUD, signed integer boundaries, UTF-8, arbitrary/empty blobs, invalid input, native lifetime cleanup, prepared queries, constraints, transactions/savepoints/commit failure, models, associations, migrations, schema alteration, pool concurrency, reconnect, and type hints.
+- The same project suite passes with Sequel 5.80.0 and 5.109.0.
+- Sequel upstream at `75b425dd1c1f34908426dd70371d14e4afb9c933`: SQLite adapter plus integration run passes (901 tests, six upstream skips). The test sources are unmodified. Some additional groups are never defined for an external adapter: seven SQLite type-conversion cases gated on `adapter_scheme == :sqlite` now have local equivalents. See [the coverage review](testing-review.md).
+- Real native HTTP execution against the official Hrana v3 Python fixture covers prepared Unicode/blob values, affected counts, inserted IDs, constraints, transactions/savepoints, reconnect, schema metadata, empty results, NULL values, models using prepared statements, and INSERT/UPDATE/DELETE RETURNING.
+- The fixture wrapper only normalizes padded/unpadded base64 between Python and Rust. SQL and stream handling stay upstream. This is a protocol integration test, not a hosted Turso test.
+- Hosted Turso remote mode was verified with a `turso://` URL normalized to HTTPS and a real database token, using Sequel 5.109.0. The warning-enabled `test/remote.rb` suite passed all five tests (24 assertions), covering CRUD, prepared bindings, Unicode/blobs, constraints, transactions/savepoints/rollback, reconnect persistence, schema metadata, models, and returning writes. Only randomly named test tables were created and dropped; credentials were not logged.
+
+## Not verified
+
+Live embedded replication, sync scheduling/read-your-writes behavior against a primary, encryption, Linux native execution, and Ruby 3.3/3.4 execution have not been tested here. The connection descriptor and sync API support replicas; that does not establish end-to-end replication correctness. Hosted remote checks do not cover token expiry/rotation, custom TLS settings, or production load behavior.
+
+## Known limits
+
+- No declared result type metadata from the C API: raw SQL/joins/CTEs/expressions need explicit hints for semantic SQLite types.
+- Existing TEXT values containing NUL are truncated by the upstream C API; the adapter rejects NUL text inputs. BLOB is binary-safe.
+- Remote native SQL parsing rejects local PRAGMAs such as busy_timeout/case_sensitive_like. Remote LIKE behavior follows the server. Local-only options are rejected when a remote URL is configured.
+- No custom regexp functions, read-only opening, loadable extensions, DQS configuration, offline-write sync mode, or configurable HTTP timeout.
+- Memory/replica pools are limited to one connection. Disconnecting a memory database destroys it.
+- Initialize in worker processes after fork; release any parent connections in `before_fork`. Child `disconnect` quietly discards inherited handles, while inherited queries remain unsupported. This cleanup does not reset an inherited native runtime or establish that reconnecting in the child is safe.
+- No automatic retry or idempotency policy for transport failures. If a write response is lost, its outcome can be uncertain.
+- `turso_libsql` 0.2.0 ships only Apple Silicon macOS and glibc Linux x86_64/aarch64 binaries. Other platforms need an independently validated driver build.
+- This targets libSQL and Turso's libSQL-compatible service, not the separate newer `turso` Rust engine API.
+
+## Upstream references
+
+- [libsql-ruby](https://github.com/tursodatabase/libsql-ruby): FFI declarations, Ruby wrappers, examples, bundled libraries. Upstream main differs from published 0.2.0 and 0.2.1.
+- [libsql-activerecord](https://github.com/tursodatabase/libsql-activerecord): ORM execution and schema comparison.
+- [Sequel SQLite adapter](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/lib/sequel/adapters/sqlite.rb) and shared SQLite modules: integration conventions and dialect behavior.
+- [sqlite3-ruby](https://github.com/sparklemotion/sqlite3-ruby): comparison of value and declared-column metadata APIs.
+- [libsql-c](https://github.com/tursodatabase/libsql-c): native ABI, ownership, descriptors, errors, and parameter conversion. Published 0.2.0-era revision: `cb3a8c2c2c7330e104e4df536189eddb83a8f491`.
+- [libsql-client-ts](https://github.com/tursodatabase/libsql-client-ts/tree/9496c782af413f6380235c7f5d0c97b5371f49b7/testing/hrana-test-server): official protocol fixture.
+- [hrana-client-ts](https://github.com/libsql/hrana-client-ts) and [libSQL](https://github.com/tursodatabase/libsql): HTTP streams, remote SQL behavior, and blob encoding.

data/docs/development.md

@@ -0,0 +1,61 @@
+# Development
+
+```sh
+bundle install
+bundle exec rake check
+```
+
+Tests use real native libSQL databases and clean up temporary files. No network service or credentials are required for the default suite. `sqlite3` is a development dependency for upstream compatibility tests; it is not loaded by the adapter.
+
+## Code checks
+
+`rake` defaults to `check`: `lint` followed by the tests. As in Sequel, tests run with `-w` and, on Ruby 3.4+, `-W:strict_unused_block`. There is no RuboCop/Standard configuration or complexity analyzer in Sequel's repository.
+
+- `bundle exec rake check_syntax` checks Ruby syntax and parser warnings in project library, test, task, and example files, plus Gemfile/Rakefile/gemspec. It fails on invalid syntax or warnings. Ignored clones, private notes, and installed gems are outside its file list.
+- `bundle exec rake check_visibility` uses Jeremy Evans' `visibility_checker`, also used by Sequel's optional visibility checks. It checks the database, dataset, and prepared dataset; changes originating in the adapter fail the task. Preexisting visibility changes inside Sequel itself are excluded.
+- `bundle exec rake lint` runs both checks.
+- `.github/workflows/ci.yml` runs `rake check` on Linux with Ruby 3.3, 3.4, and 4.0. The workflow configuration has been validated locally; those hosted jobs have not yet run for these changes.
+
+Code size was reviewed using Ruby's Prism AST to locate complete methods. No artificial complexity score is enforced. The largest configuration/type-inference methods were split by responsibility; see [testing-review.md](testing-review.md) for the measured sizes and coverage findings.
+
+## Reference sources
+
+Reference repositories are checked out under Git-ignored `tmp/upstream/`. The adapter does not load implementation code from them.
+
+```sh
+mkdir -p tmp/upstream
+git clone --depth 1 https://github.com/tursodatabase/libsql-ruby.git tmp/upstream/libsql-ruby
+git clone --depth 1 https://github.com/tursodatabase/libsql-activerecord.git tmp/upstream/libsql-activerecord
+git clone --depth 1 https://github.com/jeremyevans/sequel.git tmp/upstream/sequel
+git clone --depth 1 https://github.com/sparklemotion/sqlite3-ruby.git tmp/upstream/sqlite3-ruby
+git clone --depth 1 https://github.com/tursodatabase/libsql-c.git tmp/upstream/libsql-c
+git clone --depth 1 https://github.com/tursodatabase/libsql-client-ts.git tmp/upstream/libsql-client-ts
+git clone --depth 1 https://github.com/libsql/hrana-client-ts.git tmp/upstream/hrana-client-ts
+git clone --depth 1 --filter=blob:none --sparse https://github.com/tursodatabase/libsql.git tmp/upstream/libsql
+git -C tmp/upstream/libsql sparse-checkout set libsql/src libsql-hrana
+```
+
+`bundle exec rake upstream` runs the cloned Sequel SQLite adapter tests plus its integration suite in the upstream working directory, preserving its migration fixtures. It loads the cloned Sequel itself rather than accidentally loading two Sequel versions into one process. Tests use an in-memory database.
+
+## Native HTTP integration
+
+Prepare the official test server in an isolated Python environment:
+
+```sh
+python3.11 -m venv tmp/hrana-venv
+tmp/hrana-venv/bin/pip install -r tmp/upstream/libsql-client-ts/testing/hrana-test-server/requirements.txt
+bundle exec rake remote_local
+```
+
+The fixture needs a free localhost port 8080. It creates a temporary SQLite file, spawns the Ruby tests, then shuts down and removes its database. `test/support/hrana_server.py` fixes only the Python fixture's base64 padding incompatibility with the Rust client. No upstream source is modified.
+
+For a disposable hosted database, export `LIBSQL_TEST_URL` and `LIBSQL_TEST_AUTH_TOKEN`, then run `bundle exec rake remote`. Tests create randomly named tables and drop only those tables. Do not point destructive integration fixtures from another project at a production database.
+
+## Packaging
+
+```sh
+mkdir -p pkg
+gem build libsql-sequel.gemspec --output pkg/libsql-sequel-0.3.0.gem
+```
+
+The explicit gem file list includes Ruby library files, public docs, examples, README, and LICENSE. It excludes private notes, cloned repositories, credentials, tests, and temporary databases. Nothing is automatically published.

data/docs/testing-review.md

@@ -0,0 +1,46 @@
+# Spec and code-quality review
+
+Reviewed 2026-10-31 against the cloned upstream sources, after the initial adapter commit `0b966b1` was pushed.
+
+## Upstream comparison
+
+| Source | Existing coverage | Action here |
+| --- | --- | --- |
+| Sequel SQLite adapter + integration specs | SQL generation, schema changes, constraints, transactions, models, associations, migrations, prepared queries | Continue running unmodified upstream specs with `rake upstream` |
+| Sequel SQLite type-conversion group | Seven cases defined only for `adapter_scheme == :sqlite`; absent from the external-adapter run | Added local equivalents in `test/sqlite_types_test.rb` |
+| Sequel SQLite-specific URI, regexp, temporary-release groups | Target sqlite3-specific APIs or explicitly create `Sequel.sqlite` | Keep native libSQL URL tests and explicit rejection of unsupported regexp options; do not pretend these groups exercise this adapter |
+| libsql-activerecord | No dedicated adapter spec directory or test CI; example Rails scaffold has controller/system CRUD tests and an empty model test | Existing model tests cover local CRUD; added remote model lifecycle with Sequel's prepared-statements plugin |
+| libsql-activerecord execution code | Separates row-returning queries, batch execution, affected counts, and insert IDs | Added remote empty-result metadata, NULL values, and UPDATE/DELETE RETURNING cases |
+
+The ActiveRecord adapter cannot be tested by loading its Rails scaffold into this project: that would exercise ActiveRecord's adapter, not the Sequel implementation.
+
+## Bugs exposed by the new specs
+
+- Integer and Float timestamps now use Unix seconds and Julian days, respectively, supporting both Time and DateTime output classes.
+- Numeric TIME values now round fractional seconds to microseconds as Sequel does.
+- Numeric/text storage values in a BLOB column now become `Sequel::SQL::Blob` rather than raising or remaining plain strings.
+- Nonnumeric text in a decimal column remains text, consistent with SQLite's flexible storage and Sequel's converter.
+- Repeated `get` calls no longer lose result types once Sequel's placeholder-literalizer cache activates. The adapter disables that optimization because it hides projection origins; native bound/prepared statements still work.
+
+## Linting and size review
+
+Sequel has no RuboCop, Standard, Flog, Reek, or cyclomatic-complexity configuration. Its Rakefile supplies `check_syntax`, warning-enabled spec commands, and optional `visibility_checker` integration. Its contribution guide asks contributors to follow surrounding code style rather than prescribing an automatic formatter.
+
+This repository now provides `check_syntax`, `check_visibility`, `lint`, and `check` tasks. Syntax and visibility failures were tested with deliberately invalid temporary probes and correctly returned nonzero exit statuses. These checks apply only to project code, not ignored upstream checkouts. No wholesale reformatting was performed.
+
+Prism AST source ranges identified `Configuration#initialize` (58 lines) and `Dataset#libsql_types` (50 lines) as the longest methods. Configuration now separates location normalization, URL validation, credentials, replication options, and option validation. `ResultTypes` handles projection origins and `TypeConverter` handles semantic conversions. `Dataset` shrank from 130 to 58 lines. The longest library method is now 24 lines; the largest library file is 178 lines. These are source-size measurements, not cyclomatic scores.
+
+## Verification
+
+- `bundle exec rake check upstream remote_local`: 40 local tests / 196 assertions; 901 upstream tests / 7469 assertions / six upstream skips; five real native HTTP tests / 24 assertions. No failures or errors. Current-bundle syntax, warnings, and adapter visibility checks pass.
+- The 40 local tests also pass with Sequel 5.80.0. That older Sequel emits a Ruby 4 URI deprecation warning from its own code; it is not an adapter warning.
+- The CI workflow parses and invokes `rake check`, but its Linux/Ruby matrix has not been executed here.
+
+Hosted Turso authentication/TLS, live replica sync/read-your-writes behavior, and encryption still need real service tests. Local descriptor support or mocked native calls would not establish those guarantees, so this review does not claim them.
+
+## Source pointers
+
+- [Sequel Rakefile](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/Rakefile)
+- [Sequel SQLite specs](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/spec/adapters/sqlite_spec.rb)
+- [Sequel contribution guide](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/CONTRIBUTING)
+- [libsql-activerecord example tests](https://github.com/tursodatabase/libsql-activerecord/tree/4873624743b046dde6c0188963b22576d8341e3a/examples/railsapp/test)

data/examples/local.rb

@@ -0,0 +1,19 @@
+# frozen-string-literal: true
+
+require 'libsql-sequel'
+
+Sequel.connect(:adapter => :libsql) do |db|
+  db.create_table(:items) do
+    primary_key :id
+    String :name, :null => false
+    TrueClass :active, :default => true
+  end
+
+  items = db[:items]
+  id = items.insert(:name => 'Hello, libSQL')
+  find = items.where(:id => :$id).prepare(:first, :find_item)
+  p find.call(:id => id)
+
+  db.transaction(:rollback => :always){items.insert(:name => 'discarded')}
+  puts "#{items.count} persisted item"
+end

data/lib/libsql-sequel.rb

@@ -0,0 +1,5 @@
+# frozen-string-literal: true
+
+require 'sequel'
+require_relative 'sequel/libsql/version'
+require_relative 'sequel/adapters/libsql'

data/lib/sequel/adapters/libsql.rb

@@ -0,0 +1,178 @@
+# frozen-string-literal: true
+
+require 'sequel'
+require 'sequel/adapters/shared/sqlite'
+require_relative '../libsql/connection'
+require_relative '../libsql/configuration'
+require_relative '../libsql/dataset'
+
+module Sequel
+  module LibSQL
+    class Database < Sequel::Database
+      include Sequel::SQLite::DatabaseMethods
+
+      set_adapter_scheme :libsql
+
+      # libsql://host is a native remote URL. Use a hash for local files.
+      def self.uri_to_options(uri)
+        {:database => uri.to_s}
+      end
+      private_class_method :uri_to_options
+
+      def connect(server)
+        options = server_opts(server)
+        configuration = Configuration.new(self, options)
+        connection = Connection.new(configuration.native_options)
+        begin
+          pragmas = connection_pragmas
+          if configuration.remote?
+            # The native remote SQL parser rejects these local-only PRAGMAs.
+            pragmas = pragmas.grep(/\APRAGMA foreign_keys = /)
+          else
+            timeout = Integer(options.fetch(:timeout, 5000))
+            raise Sequel::Error, 'timeout must be a nonnegative 32-bit millisecond value' unless (0..2_147_483_647).cover?(timeout)
+            pragmas += ["PRAGMA busy_timeout = #{timeout}"]
+          end
+          pragmas.each do |sql|
+            log_connection_yield(sql, connection){connection.execute_batch(sql)}
+          end
+          connection
+        rescue Exception
+          connection.close
+          raise
+        end
+      end
+
+      def disconnect_connection(connection)
+        connection.close
+      end
+
+      # Match SQLite's unix-second and Julian-day timestamp representations.
+      def to_application_timestamp(value)
+        case value
+        when Integer
+          super(Time.at(value).to_s)
+        when Float
+          super(DateTime.jd(value).to_s)
+        else
+          super
+        end
+      end
+
+      def execute(sql, opts=OPTS, &block)
+        _execute(:select, sql, opts, &block)
+      end
+
+      def execute_dui(sql, opts=OPTS)
+        _execute(:update, sql, opts)
+      end
+
+      def execute_insert(sql, opts=OPTS)
+        _execute(:insert, sql, opts)
+      end
+
+      # DB.run accepts SQL batches, as in Sequel's SQLite adapter.
+      def execute_ddl(sql, opts=OPTS)
+        synchronize(opts[:server]) do |connection|
+          log_connection_yield(sql, connection){connection.execute_batch(sql)}
+        end
+      rescue Native::Error => e
+        raise_error(e)
+      end
+
+      # Pull remote changes into an embedded replica. Writes use the native
+      # read-your-writes setting (enabled by default).
+      def sync(opts=OPTS)
+        synchronize(opts[:server]) do |connection|
+          raise Sequel::Error, 'cannot sync inside a transaction' if in_transaction?(:server => opts[:server])
+          connection.sync
+        end
+      rescue Native::Error => e
+        raise_error(e)
+      end
+
+      private
+
+      def adapter_initialize
+        set_integer_booleans
+        self.transaction_mode = @opts[:transaction_mode].to_sym if @opts[:transaction_mode]
+      end
+
+      def connection_pool_default_options
+        options = super.dup
+        options[:max_connections] = 1 if Configuration.new(self, @opts).single_connection?
+        options
+      end
+
+      def database_error_classes
+        [Native::Error]
+      end
+
+      # Validation sends SELECT NULL, while transaction commands send no rows.
+      # The native batch API handles both without leaking a result cursor.
+      def connection_execute_method
+        :execute_batch
+      end
+
+      def database_specific_error_class(exception, opts)
+        case exception.message
+        when /libSQL connection is closed|Hrana:.*stream closed/i
+          DatabaseDisconnectError
+        when /UNIQUE constraint failed|PRIMARY KEY must be unique/i
+          UniqueConstraintViolation
+        when /NOT NULL constraint failed/i
+          NotNullConstraintViolation
+        when /FOREIGN KEY constraint failed/i
+          ForeignKeyConstraintViolation
+        when /CHECK constraint failed/i
+          CheckConstraintViolation
+        when /cannot store \w+ value in \w+ column|constraint failed/i
+          ConstraintViolation
+        else
+          super
+        end
+      end
+
+      def dataset_class_default
+        Dataset
+      end
+
+      def _execute(type, sql, opts)
+        if sql.is_a?(Symbol)
+          sql = prepared_statement(sql).prepared_sql
+        end
+        arguments = opts.fetch(:arguments, [])
+        arguments = if arguments.is_a?(Hash)
+          arguments.transform_values{|value| bound_value(value)}
+        else
+          arguments.map{|value| bound_value(value)}
+        end
+        synchronize(opts[:server]) do |connection|
+          log_connection_yield(sql, connection, opts[:arguments]) do
+            if type == :select && block_given?
+              connection.query(sql, arguments){|result| yield result}
+            else
+              changed = connection.execute(sql, arguments)
+              type == :insert ? connection.last_insert_id : changed
+            end
+          end
+        end
+      rescue Native::Error => e
+        raise_error(e)
+      end
+
+      def bound_value(value)
+        case value
+        when Time, Date, DateTime
+          literal(value)[1...-1]
+        when BigDecimal
+          value.to_s('F')
+        when true, false
+          integer_booleans ? (value ? 1 : 0) : (value ? 't' : 'f')
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/sequel/adapters/turso.rb

@@ -0,0 +1,6 @@
+# frozen-string-literal: true
+
+require_relative 'libsql'
+
+# Route Sequel.connect('turso://...') through the same adapter and pool.
+Sequel.synchronize { Sequel::ADAPTER_MAP[:turso] = Sequel::LibSQL::Database }

data/lib/sequel/libsql/configuration.rb

@@ -0,0 +1,106 @@
+# frozen-string-literal: true
+
+module Sequel
+  module LibSQL
+    # Normalize local, remote, and embedded-replica options in one place.
+    class Configuration
+      attr_reader :native_options
+
+      def initialize(db, options)
+        @db = db
+        @options = options
+        path, url = location
+        validate_url(url)
+        # Turso Cloud now supplies turso:// URLs. The pinned native driver
+        # predates that alias but supports the equivalent HTTPS endpoint.
+        url = url.sub(/\Aturso:/i, 'https:') if url
+        @native_options = {:path => path, :url => url}
+        add_credentials
+        add_replication_options
+        validate_options
+      rescue URI::InvalidURIError, ArgumentError, TypeError
+        raise Sequel::Error, 'invalid libSQL connection configuration'
+      end
+
+      def replica?
+        !!(@native_options[:path] && @native_options[:url])
+      end
+
+      def remote?
+        !!@native_options[:url]
+      end
+
+      def single_connection?
+        replica? || @native_options[:path] == ':memory:'
+      end
+
+      private
+
+      def location
+        database = @options[:database]
+        database = nil if database.to_s.empty?
+        url = @options[:url]
+        if database && /\A(?:turso|libsql|https?):\/\//i.match?(database.to_s)
+          raise Sequel::Error, 'specify the remote URL with database or url, not both' if url && url != database
+          url = database
+          database = nil
+        end
+        path = @options[:path] || database
+        raise Sequel::Error, 'path must not be empty' if path && path.to_s.empty?
+        if @options[:path] && database && @options[:path].to_s != database.to_s
+          raise Sequel::Error, 'database and path specify different local files'
+        end
+        path = ':memory:' unless path || url
+        [path && path.to_s, url && url.to_s]
+      end
+
+      def validate_url(url)
+        if url
+          uri = URI.parse(url.to_s)
+          unless %w[turso libsql https http].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.fragment && !uri.query
+            raise Sequel::Error, 'libSQL URL must use turso, libsql, https, or http with a host and no credentials, query, or fragment'
+          end
+        elsif @options[:auth_token]
+          raise Sequel::Error, 'auth_token requires a remote URL'
+        end
+      end
+
+      def add_credentials
+        [:auth_token, :encryption_key].each{|key| @native_options[key] = @options[key] if @options.key?(key)}
+        # 0.2.0 requires a non-null token pointer even for an unauthenticated
+        # local Hrana server. An empty token is the native no-auth convention.
+        @native_options[:auth_token] ||= '' if remote?
+        if @options.key?(:namespace)
+          unless CLibsql::DatabaseDesc.members.include?(:namespace)
+            raise Sequel::Error, 'namespace is not supported by this turso_libsql release'
+          end
+          @native_options[:namespace] = @options[:namespace]
+        end
+      end
+
+      def add_replication_options
+        @native_options[:read_your_writes] = @db.send(:typecast_value_boolean, @options.fetch(:read_your_writes, true))
+        interval = Integer(@options.fetch(:sync_interval, 0))
+        raise Sequel::Error, 'sync_interval must be an unsigned 64-bit millisecond interval' unless (0...(1 << 64)).cover?(interval)
+        raise Sequel::Error, 'sync_interval requires an embedded replica' if interval > 0 && !replica?
+        raise Sequel::Error, 'an embedded replica requires a file path, not :memory:' if replica? && @native_options[:path] == ':memory:'
+        @native_options[:sync_interval] = interval
+      end
+
+      def validate_options
+        if remote?
+          [:timeout, :case_sensitive_like, :auto_vacuum, :synchronous, :temp_store].each do |key|
+            raise Sequel::Error, "#{key} is only supported for local libSQL databases" if @options.key?(key)
+          end
+        end
+
+        [:readonly, :disable_dqs, :setup_regexp_function, :synced, :webpki].each do |key|
+          raise Sequel::Error, "#{key} is not supported by this adapter" if @options.key?(key)
+        end
+        if single_connection? && Integer(@options.fetch(:max_connections, 1)) != 1
+          raise Sequel::Error, 'memory databases and embedded replicas require max_connections: 1'
+        end
+      end
+    end
+  end
+end

data/lib/sequel/libsql/connection.rb

@@ -0,0 +1,165 @@
+# frozen-string-literal: true
+
+require_relative 'native'
+
+module Sequel
+  module LibSQL
+    # Owns a native database and its connection for one Sequel pool slot.
+    class Connection
+      def initialize(options)
+        @pid = Process.pid
+        @replica = options[:path] && options[:url]
+        desc = CLibsql::DatabaseDesc.new
+        @strings = []
+        [:path, :url, :auth_token, :encryption_key, :namespace].each do |key|
+          next if options[key].nil?
+          desc[key] = pointer = FFI::MemoryPointer.from_string(Native.string(options[key]))
+          @strings << pointer
+        end
+        desc[:sync_interval] = options.fetch(:sync_interval, 0)
+        desc[:disable_read_your_writes] = !options.fetch(:read_your_writes, true)
+        @database = Native.check(Native.database_init(desc))
+        begin
+          @connection = Native.check(Native.database_connect(@database))
+        rescue Exception
+          close
+          raise
+        end
+      end
+
+      def execute(sql, arguments = [])
+        with_statement(sql, arguments) do |statement|
+          Native.check(Native.statement_execute(statement))[:rows_changed]
+        end
+      end
+
+      def execute_batch(sql)
+        check_open
+        Native.check(Native.connection_batch(@connection, Native.string(sql)))
+        nil
+      end
+
+      def query(sql, arguments = [])
+        with_statement(sql, arguments) do |statement|
+          result = Result.new(Native.check(Native.statement_query(statement)))
+          begin
+            yield result
+          ensure
+            result.close
+          end
+        end
+      end
+
+      def last_insert_id
+        check_open
+        Native.check(Native.connection_info(@connection))[:last_inserted_id]
+      end
+
+      def sync
+        check_open
+        raise Sequel::Error, 'sync requires an embedded replica (both path and remote URL)' unless @replica
+        result = Native.check(Native.database_sync(@database))
+        {:frame_no => result[:frame_no], :frames_synced => result[:frames_synced]}
+      end
+
+      def close
+        # Inherited handles belong to the parent; their runtime cannot be used
+        # or destroyed in the child. Let Sequel empty the child's pool safely.
+        if @pid != Process.pid
+          @connection = @database = @strings = nil
+          return
+        end
+        if @connection
+          CLibsql.libsql_connection_deinit(@connection)
+          @connection = nil
+        end
+        if @database
+          CLibsql.libsql_database_deinit(@database)
+          @database = nil
+        end
+        @strings = nil
+        nil
+      end
+
+      private
+
+      def check_process
+        raise Sequel::Error, 'libSQL connections cannot be used after fork; connect inside each worker' unless @pid == Process.pid
+      end
+
+      def check_open
+        check_process
+        raise Native::Error, 'libSQL connection is closed' unless @connection
+      end
+
+      def with_statement(sql, arguments)
+        check_open
+        statement = Native.check(Native.connection_prepare(@connection, Native.string(sql)))
+        begin
+          case arguments
+          when Array
+            arguments.each do |value|
+              Native.bind_value(value){|v| Native.check(CLibsql.libsql_statement_bind_value(statement, v))}
+            end
+          when Hash
+            arguments.each do |name, value|
+              name = Native.string(name)
+              name = ":#{name}" unless /\A[:@$]/.match?(name)
+              Native.bind_value(value){|v| Native.check(CLibsql.libsql_statement_bind_named(statement, name, v))}
+            end
+          else
+            raise Sequel::Error, 'libSQL arguments must be an Array or Hash'
+          end
+          yield statement
+        ensure
+          CLibsql.libsql_statement_deinit(statement)
+        end
+      end
+    end
+
+    # Only lives inside Connection#query; rows are freed even on break or raise.
+    class Result
+      def initialize(rows)
+        @rows = rows
+      end
+
+      def columns
+        check_open
+        @columns ||= Array.new(Native.rows_column_count(@rows)) do |index|
+          Native.read_slice(CLibsql.libsql_rows_column_name(@rows, index), true)
+        end
+      end
+
+      def each
+        check_open
+        loop do
+          check_open
+          row = Native.check(Native.rows_next(@rows))
+          break if row[:inner].null?
+          begin
+            values = Array.new(columns.length) do |index|
+              Native.value(Native.check(CLibsql.libsql_row_value(row, index))[:ok])
+            end
+            yield values
+          ensure
+            CLibsql.libsql_row_deinit(row)
+          end
+        end
+      end
+
+      def close
+        if @rows
+          CLibsql.libsql_rows_deinit(@rows)
+          @rows = nil
+        end
+        nil
+      end
+
+      private
+
+      def check_open
+        raise Native::Error, 'libSQL result is closed' unless @rows
+      end
+    end
+  end
+end

data/lib/sequel/libsql/dataset.rb

@@ -0,0 +1,58 @@
+# frozen-string-literal: true
+
+require_relative 'result_types'
+require_relative 'type_converter'
+
+module Sequel
+  module LibSQL
+    class Dataset < Sequel::Dataset
+      include Sequel::SQLite::DatasetMethods
+
+      BindArgumentMethods = prepared_statements_module(:bind, Sequel::Dataset::UnnumberedArgumentMapper)
+      PreparedStatementMethods = prepared_statements_module(:prepare, BindArgumentMethods)
+
+      # Explicit conversions for raw SQL, expressions, or ambiguous projections.
+      # DB.fetch(sql).with_libsql_types(:active=>:boolean, :created_at=>:datetime)
+      def with_libsql_types(types)
+        clone(:libsql_types => (@opts[:libsql_types] || OPTS).merge(types).freeze)
+      end
+
+      # Cached literalizers replace selected columns with opaque arguments.
+      # Without C decltypes, keep the projection AST for stable conversions.
+      def supports_placeholder_literalizer?
+        false
+      end
+
+      def fetch_rows(sql)
+        execute(sql) do |result|
+          columns = result.columns.map{|column| output_identifier(column)}
+          types = ResultTypes.new(self).for_columns(columns)
+          converter = TypeConverter.new(db)
+          self.columns = columns
+          result.each do |values|
+            row = {}
+            columns.each_with_index do |name, index|
+              value = values[index]
+              row[name] = converter.call(value, types[name])
+            end
+            yield row
+          end
+        end
+      end
+
+      private
+
+      def bound_variable_modules
+        [BindArgumentMethods]
+      end
+
+      def prepared_statement_modules
+        [PreparedStatementMethods]
+      end
+
+      def literal_string_append(sql, value)
+        sql << "'" << Native.string(value).gsub("'", "''") << "'"
+      end
+    end
+  end
+end

data/lib/sequel/libsql/native.rb

@@ -0,0 +1,115 @@
+# frozen-string-literal: true
+
+gem 'turso_libsql', '= 0.2.0'
+require 'libsql'
+
+module Sequel
+  module LibSQL
+    # Private compatibility boundary for turso_libsql 0.2.x. Its high-level
+    # wrappers have unsafe error handling and incorrect value conversions.
+    # Reuse its ABI structs and library, without changing global driver classes.
+    module Native
+      class Error < StandardError; end
+
+      extend FFI::Library
+      ffi_lib(*CLibsql.ffi_libraries.map(&:name))
+
+      {
+        :database_init => [[CLibsql::DatabaseDesc.by_value], CLibsql::Database.by_value],
+        :database_connect => [[CLibsql::Database.by_value], CLibsql::Connection.by_value],
+        :database_sync => [[CLibsql::Database.by_value], CLibsql::Sync.by_value],
+        :connection_prepare => [[CLibsql::Connection.by_value, :string], CLibsql::Statement.by_value],
+        :connection_info => [[CLibsql::Connection.by_value], CLibsql::ConnectionInfo.by_value],
+        :connection_batch => [[CLibsql::Connection.by_value, :string], CLibsql::Batch.by_value],
+        :statement_execute => [[CLibsql::Statement.by_value], CLibsql::Execute.by_value],
+        :statement_query => [[CLibsql::Statement.by_value], CLibsql::Rows.by_value],
+        :rows_next => [[CLibsql::Rows.by_value], CLibsql::Row.by_value]
+      }.each do |name, (args, result)|
+        attach_function name, :"libsql_#{name}", args, result, :blocking => true
+      end
+
+      # The upstream declaration incorrectly uses Row.by_value for this call.
+      attach_function :slice_deinit, :libsql_slice_deinit, [CLibsql::Slice.by_value], :void
+
+      # The released gem and upstream main use different names for this symbol.
+      count_function = CLibsql.respond_to?(:libsql_rows_column_count) ? :libsql_rows_column_count : :libsql_rows_column_length
+      attach_function :rows_column_count, count_function, [CLibsql::Rows.by_value], :int32
+
+      def self.check(result)
+        return result if result[:err].null?
+
+        begin
+          message = CLibsql.libsql_error_message(result[:err])
+        ensure
+          CLibsql.libsql_error_deinit(result[:err])
+        end
+        raise Error, message
+      end
+
+      def self.string(value)
+        value = value.to_s.encode(Encoding::UTF_8)
+        raise Sequel::Error, 'libSQL text cannot contain NUL bytes; use Sequel.blob for binary data' if value.include?("\0")
+        raise Sequel::Error, 'libSQL text must be valid UTF-8' unless value.valid_encoding?
+        value
+      rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+        raise Sequel::Error, 'libSQL text must be convertible to UTF-8; use Sequel.blob for binary data'
+      end
+
+      # C text slices include a terminal NUL; blob slices do not.
+      def self.read_slice(slice, text)
+        return text ? '' : Sequel.blob('') if slice[:ptr].null?
+
+        begin
+          length = slice[:len]
+          value = slice[:ptr].read_string_length(text ? [length - 1, 0].max : length)
+          text ? value.force_encoding(Encoding::UTF_8) : Sequel.blob(value)
+        ensure
+          slice_deinit(slice)
+        end
+      end
+
+      def self.value(value)
+        case value[:type]
+        when :null
+          nil
+        when :integer
+          # The Ruby driver declares uint64, while the C API returns int64.
+          integer = value[:value][:integer]
+          integer >= (1 << 63) ? integer - (1 << 64) : integer
+        when :real
+          value[:value][:real]
+        when :text, :blob
+          read_slice(value[:value][value[:type]], value[:type] == :text)
+        else
+          raise Error, 'unknown libSQL value type'
+        end
+      end
+
+      # Keep the input pointer alive until the native bind has copied its bytes.
+      def self.bind_value(value)
+        case value
+        when nil
+          yield CLibsql.libsql_null
+        when Integer
+          unless (-(1 << 63)...(1 << 63)).cover?(value)
+            raise Sequel::Error, 'libSQL integers must fit in signed 64 bits'
+          end
+          yield CLibsql.libsql_integer(value)
+        when Float
+          raise Sequel::Error, 'libSQL cannot bind non-finite floats' unless value.finite?
+          yield CLibsql.libsql_real(value)
+        when SQL::Blob
+          pointer = FFI::MemoryPointer.new(:char, [value.bytesize, 1].max)
+          pointer.put_bytes(0, value)
+          yield CLibsql.libsql_blob(pointer, value.bytesize)
+        when String
+          value = string(value)
+          pointer = FFI::MemoryPointer.from_string(value)
+          yield CLibsql.libsql_text(pointer, value.bytesize)
+        else
+          raise Sequel::Error, "unsupported libSQL bound value type: #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/sequel/libsql/result_types.rb

@@ -0,0 +1,91 @@
+# frozen-string-literal: true
+
+module Sequel
+  module LibSQL
+    # Resolve only projections with a known table-column origin. C exposes no
+    # declared types, so raw SQL and ambiguous result columns need explicit hints.
+    class ResultTypes
+      def initialize(dataset)
+        @dataset = dataset
+        @opts = dataset.opts
+      end
+
+      def for_columns(columns)
+        types = inferred_types
+        columns.tally.each{|name, count| types.delete(name) if count > 1}
+        types.merge(@opts[:libsql_types] || OPTS)
+      end
+
+      private
+
+      def inferred_types
+        if original = @opts[:orig_dataset]
+          return self.class.new(original).send(:inferred_types)
+        end
+        return {} unless table = source_table
+        selection = @opts[:returning] || @opts[:select]
+        return {} if selection && !selection.empty? && selection.none?{|column| column?(column)}
+
+        schema = @dataset.db.schema(table).to_h
+        return schema.transform_values{|info| info[:type]} if !selection || selection.empty?
+        types = {}
+        selection.each{|column| add_projection(types, schema, column)}
+        types
+      end
+
+      def source_table
+        return if [:sql, :join, :with, :compounds].any?{|key| @opts[key]}
+        sources = @opts[:from]
+        return unless sources && sources.length == 1
+        source = sources.first
+        source = source.expression if source.is_a?(SQL::AliasedExpression)
+        source if identifier?(source) || source.is_a?(String)
+      end
+
+      def add_projection(types, schema, column)
+        if column.is_a?(SQL::ColumnAll)
+          return schema.each{|name, info| types[name] = info[:type]}
+        end
+        name, aliaz = column_names(column)
+        if name && (info = schema[output_identifier(name)])
+          types[output_identifier(aliaz || name)] = info[:type]
+        elsif aliaz
+          types.delete(output_identifier(aliaz))
+        end
+      end
+
+      def column_names(column)
+        aliaz = nil
+        if column.is_a?(SQL::AliasedExpression)
+          aliaz = column.alias
+          column = column.expression
+        end
+        name = case column
+        when Symbol
+          _, name, symbol_alias = @dataset.send(:split_symbol, column)
+          aliaz ||= symbol_alias
+          name
+        when SQL::Identifier
+          column.value
+        when SQL::QualifiedIdentifier
+          column.column
+        end
+        [name, aliaz]
+      end
+
+      def column?(column)
+        column = column.expression if column.is_a?(SQL::AliasedExpression)
+        identifier?(column) || column.is_a?(SQL::ColumnAll)
+      end
+
+      def identifier?(value)
+        value.is_a?(Symbol) || value.is_a?(SQL::Identifier) || value.is_a?(SQL::QualifiedIdentifier)
+      end
+
+      def output_identifier(value)
+        value = value.value if value.is_a?(SQL::Identifier)
+        @dataset.send(:output_identifier, value)
+      end
+    end
+  end
+end

data/lib/sequel/libsql/type_converter.rb

@@ -0,0 +1,53 @@
+# frozen-string-literal: true
+
+module Sequel
+  module LibSQL
+    # Apply SQLite's semantic types after decoding the native storage value.
+    class TypeConverter
+      FALSE_VALUES = [0, '0', 'false', 'f', 'no', 'n'].freeze
+
+      def initialize(database)
+        @database = database
+      end
+
+      def call(value, type)
+        return nil if value.nil?
+        return type.call(value) if type.respond_to?(:call)
+        case type
+        when :boolean
+          !FALSE_VALUES.include?(value.is_a?(String) ? value.downcase : value)
+        when :date
+          value.is_a?(Numeric) ? Date.jd(value.to_i) : Sequel.string_to_date(value)
+        when :datetime, :timestamp
+          @database.to_application_timestamp(value)
+        when :time
+          time(value)
+        when :decimal
+          decimal(value)
+        when :integer
+          value.to_i
+        when :float
+          value.to_f
+        when :blob
+          Sequel.blob(value.to_s)
+        else
+          value
+        end
+      end
+
+      private
+
+      def time(value)
+        return Sequel.string_to_time(value) if value.is_a?(String)
+        seconds, fraction = value.divmod(1)
+        SQLTime.create(seconds / 3600, (seconds % 3600) / 60, seconds % 60, (fraction * 1_000_000).round)
+      end
+
+      def decimal(value)
+        BigDecimal(value.to_s)
+      rescue ArgumentError
+        value.to_s
+      end
+    end
+  end
+end

data/lib/sequel/libsql/version.rb

@@ -0,0 +1,7 @@
+# frozen-string-literal: true
+
+module Sequel
+  module LibSQL
+    VERSION = '0.3.0'
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: libsql-sequel
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Francesco Canessa
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.80'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.80'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: turso_libsql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: Sequel SQL, models, migrations, and transactions using the native libSQL
+  Ruby driver.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/architecture.md
+- docs/compatibility.md
+- docs/development.md
+- docs/testing-review.md
+- examples/local.rb
+- lib/libsql-sequel.rb
+- lib/sequel/adapters/libsql.rb
+- lib/sequel/adapters/turso.rb
+- lib/sequel/libsql/configuration.rb
+- lib/sequel/libsql/connection.rb
+- lib/sequel/libsql/dataset.rb
+- lib/sequel/libsql/native.rb
+- lib/sequel/libsql/result_types.rb
+- lib/sequel/libsql/type_converter.rb
+- lib/sequel/libsql/version.rb
+homepage: https://github.com/makevoid/libsql-sequel
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A libSQL and Turso adapter for Sequel
+test_files: []