rubydb 0.1.3 → 0.1.5

data/docs/server/protocol.md

@@ -1,12 +1,12 @@
-# RubyDB server protocol
-
-The client/server protocol uses bounded framed requests and responses with
-handshake, authentication, query, prepared statement, transaction, health, and
-metrics operations. Frames must be size-limited and malformed input must be
-rejected without taking down the server.
-
-Query deadlines and in-flight cancellation are request-scoped. Cancellation is
-cooperative and must be checked by long-running execution paths. Do not expose
-the listener publicly; use TLS/private networking and rotate credentials through
-the documented operations procedure. The normative notes are in
-`spec/wire/protocol.md` and `spec/protocol/protocol.md`.
+# RubyDB server protocol
+
+The client/server protocol uses bounded framed requests and responses with
+handshake, authentication, query, prepared statement, transaction, health, and
+metrics operations. Frames must be size-limited and malformed input must be
+rejected without taking down the server.
+
+Query deadlines and in-flight cancellation are request-scoped. Cancellation is
+cooperative and must be checked by long-running execution paths. Do not expose
+the listener publicly; use TLS/private networking and rotate credentials through
+the documented operations procedure. The normative notes are in
+`spec/wire/protocol.md` and `spec/protocol/protocol.md`.

data/docs/sql/compatibility-guide.md

@@ -1,82 +1,82 @@
-# SQL compatibility guide
-
-This page is a developer reference for evaluating SQL support. The normative
-statement list is [SQL compatibility](compatibility.md); the SQLite-style
-application profile is [here](sqlite-compatibility.md). RubyDB does not claim
-complete PostgreSQL, MySQL, or SQLite dialect compatibility.
-
-## Compatibility has four layers
-
-An SQL feature is production-ready only when all four layers agree:
-
-1. syntax is parsed and rejected with useful errors;
-2. binding and type rules are defined, including `NULL`;
-3. planner/executor results and transaction semantics are correct; and
-4. Ruby, client/server, and ActiveRecord paths behave consistently.
-
-A parser accepting a statement is not sufficient. Test duplicate rows,
-ordering, aggregates, joins, constraints, rollback, savepoints, indexes,
-timeouts, and recovery for every feature that mutates or reads data.
-
-## Query review checklist
-
-For each query shape, record schema, indexes, bind types, expected rows,
-expected ordering, transaction isolation, and error behavior. Test empty,
-single-row, duplicate, `NULL`, and large-result cases. Explicitly order results
-when the application requires order; relational results are not inherently
-ordered.
-
-Review:
-
-* projections and aliases;
-* boolean precedence and `NULL` truth tables;
-* inner, left, and multi-table joins;
-* grouping, aggregate input, and `HAVING`;
-* limits and offsets at boundaries;
-* conflict/upsert behavior and affected-row counts;
-* casts, defaults, and constraint errors; and
-* snapshot visibility during concurrent writes.
-
-## Application migration from SQLite
-
-Start with a schema dump and a representative query/migration inventory. Run
-the application test suite against RubyDB, not only a few hand-written
-queries. Review pragmas, virtual tables, FTS, extensions, custom functions,
-file-format assumptions, recursive queries, date/time behavior, collations,
-and error handling. These areas are not included merely because the common
-profile looks SQLite-like.
-
-Never point RubyDB at an existing SQLite file and expect it to open. Migrate
-through an explicit export/import process with checksums, row counts, and
-application-level verification.
-
-## SQL change workflow
-
-Add a contract example under `spec/sql`, parser tests, execution tests, failure
-tests, and adapter coverage when relevant. Update the compatibility page and
-release notes. Add a regression for every bug. If semantics are intentionally
-different from another database, document the difference with a migration
-recommendation.
-
-## Safe examples
-
-```sql
-CREATE TABLE IF NOT EXISTS users (
-  id INTEGER PRIMARY KEY,
-  email TEXT NOT NULL UNIQUE,
-  active BOOLEAN DEFAULT TRUE
-);
-
-INSERT INTO users (email, active) VALUES (?, ?);
-
-SELECT active, COUNT(*) AS total
-FROM users
-WHERE email IS NOT NULL
-GROUP BY active
-HAVING COUNT(*) > 0
-ORDER BY active;
-```
-
-Use bound parameters from Ruby or ActiveRecord. Do not construct SQL by
-concatenating user input.
-
+# SQL compatibility guide
+
+This page is a developer reference for evaluating SQL support. The normative
+statement list is [SQL compatibility](compatibility.md); the SQLite-style
+application profile is [here](sqlite-compatibility.md). RubyDB does not claim
+complete PostgreSQL, MySQL, or SQLite dialect compatibility.
+
+## Compatibility has four layers
+
+An SQL feature is production-ready only when all four layers agree:
+
+1. syntax is parsed and rejected with useful errors;
+2. binding and type rules are defined, including `NULL`;
+3. planner/executor results and transaction semantics are correct; and
+4. Ruby, client/server, and ActiveRecord paths behave consistently.
+
+A parser accepting a statement is not sufficient. Test duplicate rows,
+ordering, aggregates, joins, constraints, rollback, savepoints, indexes,
+timeouts, and recovery for every feature that mutates or reads data.
+
+## Query review checklist
+
+For each query shape, record schema, indexes, bind types, expected rows,
+expected ordering, transaction isolation, and error behavior. Test empty,
+single-row, duplicate, `NULL`, and large-result cases. Explicitly order results
+when the application requires order; relational results are not inherently
+ordered.
+
+Review:
+
+* projections and aliases;
+* boolean precedence and `NULL` truth tables;
+* inner, left, and multi-table joins;
+* grouping, aggregate input, and `HAVING`;
+* limits and offsets at boundaries;
+* conflict/upsert behavior and affected-row counts;
+* casts, defaults, and constraint errors; and
+* snapshot visibility during concurrent writes.
+
+## Application migration from SQLite
+
+Start with a schema dump and a representative query/migration inventory. Run
+the application test suite against RubyDB, not only a few hand-written
+queries. Review pragmas, virtual tables, FTS, extensions, custom functions,
+file-format assumptions, recursive queries, date/time behavior, collations,
+and error handling. These areas are not included merely because the common
+profile looks SQLite-like.
+
+Never point RubyDB at an existing SQLite file and expect it to open. Migrate
+through an explicit export/import process with checksums, row counts, and
+application-level verification.
+
+## SQL change workflow
+
+Add a contract example under `spec/sql`, parser tests, execution tests, failure
+tests, and adapter coverage when relevant. Update the compatibility page and
+release notes. Add a regression for every bug. If semantics are intentionally
+different from another database, document the difference with a migration
+recommendation.
+
+## Safe examples
+
+```sql
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  active BOOLEAN DEFAULT TRUE
+);
+
+INSERT INTO users (email, active) VALUES (?, ?);
+
+SELECT active, COUNT(*) AS total
+FROM users
+WHERE email IS NOT NULL
+GROUP BY active
+HAVING COUNT(*) > 0
+ORDER BY active;
+```
+
+Use bound parameters from Ruby or ActiveRecord. Do not construct SQL by
+concatenating user input.
+

data/docs/sql/compatibility.md

@@ -1,39 +1,39 @@
-# RubyDB SQL compatibility
-
-RubyDB supports a deliberately documented SQL dialect. It includes a tested
-SQLite-style compatibility profile for common new Ruby/Rails applications (see
-`sqlite-compatibility.md`), but this is not a claim of complete SQLite,
-PostgreSQL, or MySQL compatibility.
-
-Supported and tested statements include:
-
-- `SELECT` with projections, `WHERE`, ordering, limits, offsets, built-in
-  expressions, and `COUNT`, `SUM`, `AVG`, `MIN`, and `MAX` aggregates (including
-  `DISTINCT` aggregate arguments) with
-  `GROUP BY` and `HAVING`
-- window ranking functions `ROW_NUMBER`, `RANK`, and `DENSE_RANK`, plus
-  partition-wide and explicit `ROWS`-framed aggregate windows using
-  `OVER (PARTITION BY ... ORDER BY ...)`
-- `UNION`, `UNION ALL`, `INTERSECT`, and `EXCEPT` for compatible SELECT
-  projections
-- non-correlated scalar subqueries, `IN (SELECT ...)`, and `EXISTS (SELECT ...)`
-  predicates
-- materialized non-recursive and bounded recursive `WITH` common table
-  expressions
-- `INSERT`, `UPDATE`, and `DELETE`, including multi-row `VALUES`,
-  `ON CONFLICT DO NOTHING`, and targeted `ON CONFLICT (...) DO UPDATE SET ...`
-  with `excluded.column`
-- `CREATE TABLE` and `DROP TABLE`, including primary keys, unique constraints,
-  checks, foreign keys, and referential actions
-- `CREATE INDEX`/`CREATE UNIQUE INDEX` and `DROP INDEX`
-- `ALTER TABLE` add/drop columns and constraints
-- `CREATE`/`DROP DATABASE`, `CREATE`/`DROP SCHEMA`, and `CREATE`/`DROP VIEW`
-- supported trigger metadata DDL: `CREATE TRIGGER ... EXECUTE FUNCTION ...`
-- `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `ROLLBACK TO SAVEPOINT`, and
-  `RELEASE SAVEPOINT`
-- `EXPLAIN`, `EXPLAIN ANALYZE`, and `VACUUM`
-
-Unsupported syntax must fail with a parser or execution error. RubyDB does not
-promise arbitrary SQL extensions, PostgreSQL wire-level compatibility, or
-feature parity with another database engine. The executable contract is the
-integration coverage under `spec/`.
+# RubyDB SQL compatibility
+
+RubyDB supports a deliberately documented SQL dialect. It includes a tested
+SQLite-style compatibility profile for common new Ruby/Rails applications (see
+`sqlite-compatibility.md`), but this is not a claim of complete SQLite,
+PostgreSQL, or MySQL compatibility.
+
+Supported and tested statements include:
+
+- `SELECT` with projections, `WHERE`, ordering, limits, offsets, built-in
+  expressions, and `COUNT`, `SUM`, `AVG`, `MIN`, and `MAX` aggregates (including
+  `DISTINCT` aggregate arguments) with
+  `GROUP BY` and `HAVING`
+- window ranking functions `ROW_NUMBER`, `RANK`, and `DENSE_RANK`, plus
+  partition-wide and explicit `ROWS`-framed aggregate windows using
+  `OVER (PARTITION BY ... ORDER BY ...)`
+- `UNION`, `UNION ALL`, `INTERSECT`, and `EXCEPT` for compatible SELECT
+  projections
+- non-correlated scalar subqueries, `IN (SELECT ...)`, and `EXISTS (SELECT ...)`
+  predicates
+- materialized non-recursive and bounded recursive `WITH` common table
+  expressions
+- `INSERT`, `UPDATE`, and `DELETE`, including multi-row `VALUES`,
+  `ON CONFLICT DO NOTHING`, and targeted `ON CONFLICT (...) DO UPDATE SET ...`
+  with `excluded.column`
+- `CREATE TABLE` and `DROP TABLE`, including primary keys, unique constraints,
+  checks, foreign keys, and referential actions
+- `CREATE INDEX`/`CREATE UNIQUE INDEX` and `DROP INDEX`
+- `ALTER TABLE` add/drop columns and constraints
+- `CREATE`/`DROP DATABASE`, `CREATE`/`DROP SCHEMA`, and `CREATE`/`DROP VIEW`
+- supported trigger metadata DDL: `CREATE TRIGGER ... EXECUTE FUNCTION ...`
+- `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `ROLLBACK TO SAVEPOINT`, and
+  `RELEASE SAVEPOINT`
+- `EXPLAIN`, `EXPLAIN ANALYZE`, and `VACUUM`
+
+Unsupported syntax must fail with a parser or execution error. RubyDB does not
+promise arbitrary SQL extensions, PostgreSQL wire-level compatibility, or
+feature parity with another database engine. The executable contract is the
+integration coverage under `spec/`.

data/docs/sql/data-types.md

@@ -1,10 +1,10 @@
-# SQL data types
-
-The documented RubyDB types are `INTEGER`, `BIGINT`, `SMALLINT`, `FLOAT`,
-`DECIMAL`, `BOOLEAN`, `TEXT`, `VARCHAR`, `BLOB`, `DATE`, `TIME`, `TIMESTAMP`,
-`JSON`, and `UUID`. Type conversion, nullability, defaults, and constraint
-behavior are validated through the SQL and Rails suites.
-
-RubyDB does not claim storage or coercion compatibility with every other SQL
-engine. Preserve types explicitly in migrations and test application boundary
-values, nulls, booleans, timestamps, decimals, JSON, and binary data.
+# SQL data types
+
+The documented RubyDB types are `INTEGER`, `BIGINT`, `SMALLINT`, `FLOAT`,
+`DECIMAL`, `BOOLEAN`, `TEXT`, `VARCHAR`, `BLOB`, `DATE`, `TIME`, `TIMESTAMP`,
+`JSON`, and `UUID`. Type conversion, nullability, defaults, and constraint
+behavior are validated through the SQL and Rails suites.
+
+RubyDB does not claim storage or coercion compatibility with every other SQL
+engine. Preserve types explicitly in migrations and test application boundary
+values, nulls, booleans, timestamps, decimals, JSON, and binary data.

data/docs/sql/functions.md

@@ -1,9 +1,9 @@
-# SQL functions
-
-The tested function surface includes `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`,
-`LOWER`, `UPPER`, `LENGTH`, `SUBSTR`, `CONCAT`, `COALESCE`, and `NULLIF`, plus
-the documented window ranking and aggregate functions.
-
-Function null behavior and return types are part of the compatibility contract.
-Do not assume a PostgreSQL, MySQL, or SQLite extension exists because a function
-has the same name; unsupported functions must be reported explicitly.
+# SQL functions
+
+The tested function surface includes `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`,
+`LOWER`, `UPPER`, `LENGTH`, `SUBSTR`, `CONCAT`, `COALESCE`, and `NULLIF`, plus
+the documented window ranking and aggregate functions.
+
+Function null behavior and return types are part of the compatibility contract.
+Do not assume a PostgreSQL, MySQL, or SQLite extension exists because a function
+has the same name; unsupported functions must be reported explicitly.

data/docs/sql/joins.md

@@ -1,9 +1,9 @@
-# SQL joins
-
-RubyDB supports qualified `INNER`, `LEFT [OUTER]`, `RIGHT`, `FULL [OUTER]`, and
-`CROSS JOIN` forms with `ON` predicates in the documented dialect. Outer joins
-preserve unmatched rows with null-extended columns.
-
-Use explicit table qualification when columns are ambiguous. Validate join
-cardinality, null behavior, ordering, grouping, and transaction visibility with
-representative data. Join reordering is limited to safe inner-join plans.
+# SQL joins
+
+RubyDB supports qualified `INNER`, `LEFT [OUTER]`, `RIGHT`, `FULL [OUTER]`, and
+`CROSS JOIN` forms with `ON` predicates in the documented dialect. Outer joins
+preserve unmatched rows with null-extended columns.
+
+Use explicit table qualification when columns are ambiguous. Validate join
+cardinality, null behavior, ordering, grouping, and transaction visibility with
+representative data. Join reordering is limited to safe inner-join plans.

data/docs/sql/operators.md

@@ -1,9 +1,9 @@
-# SQL operators and predicates
-
-The documented surface includes arithmetic, comparison, boolean `AND`/`OR` and
-`NOT`, `IS NULL`/`IS NOT NULL`, `BETWEEN`, `IN`, `EXISTS`, `LIKE`, `ILIKE`, and
-three-valued null behavior covered by the SQL tests.
-
-Use bound parameters for user input. Test false, null, empty string, numeric
-precision, and mixed-type values explicitly; similar syntax across SQL engines
-does not guarantee identical semantics.
+# SQL operators and predicates
+
+The documented surface includes arithmetic, comparison, boolean `AND`/`OR` and
+`NOT`, `IS NULL`/`IS NOT NULL`, `BETWEEN`, `IN`, `EXISTS`, `LIKE`, `ILIKE`, and
+three-valued null behavior covered by the SQL tests.
+
+Use bound parameters for user input. Test false, null, empty string, numeric
+precision, and mixed-type values explicitly; similar syntax across SQL engines
+does not guarantee identical semantics.

data/docs/sql/sqlite-compatibility.md

@@ -1,21 +1,21 @@
-# SQLite compatibility profile
-
-RubyDB now maintains an explicit SQLite-style compatibility profile for new
-Ruby and Rails applications. The profile is tested by
-`spec/sqlite_compatibility_spec.rb` and covers the common application surface:
-
-- `CREATE TABLE IF NOT EXISTS`, integer primary keys with `AUTOINCREMENT`,
-  defaults, `NOT NULL`, and `UNIQUE`
-- CRUD, parameter binding through the Rails connection, transactions, and
-  rollback
-- `WHERE`, `IS NULL`/boolean predicates, ordering, `LIMIT`/`OFFSET`, joins,
-  grouped aggregates, and `HAVING`
-- targeted `ON CONFLICT ... DO UPDATE` upserts
-- ActiveRecord schema inspection through the embedded adapter
-
-This is useful for applications written against the documented RubyDB surface,
-but it is not a complete replacement for the SQLite library. SQLite pragmas,
-virtual tables, FTS, recursive query edge cases, extension APIs, file-format
-compatibility, and every SQLite function/error behavior remain unsupported or
-unverified. An existing SQLite application must run its own migration and
-query suite before migration.
+# SQLite compatibility profile
+
+RubyDB now maintains an explicit SQLite-style compatibility profile for new
+Ruby and Rails applications. The profile is tested by
+`spec/sqlite_compatibility_spec.rb` and covers the common application surface:
+
+- `CREATE TABLE IF NOT EXISTS`, integer primary keys with `AUTOINCREMENT`,
+  defaults, `NOT NULL`, and `UNIQUE`
+- CRUD, parameter binding through the Rails connection, transactions, and
+  rollback
+- `WHERE`, `IS NULL`/boolean predicates, ordering, `LIMIT`/`OFFSET`, joins,
+  grouped aggregates, and `HAVING`
+- targeted `ON CONFLICT ... DO UPDATE` upserts
+- ActiveRecord schema inspection through the embedded adapter
+
+This is useful for applications written against the documented RubyDB surface,
+but it is not a complete replacement for the SQLite library. SQLite pragmas,
+virtual tables, FTS, recursive query edge cases, extension APIs, file-format
+compatibility, and every SQLite function/error behavior remain unsupported or
+unverified. An existing SQLite application must run its own migration and
+query suite before migration.

data/docs/sql/syntax.md

@@ -1,10 +1,10 @@
-# SQL syntax
-
-Statements are parsed by RubyDB's lexer and parser and executed through the
-planner. The supported statements include `SELECT`, `INSERT`, `UPDATE`,
-`DELETE`, table/index/schema/view DDL, transactions/savepoints, `EXPLAIN`, and
-`VACUUM` as listed in [compatibility](compatibility.md).
-
-Use semicolons for multiple statements only where the client path supports
-them. Identifiers may be quoted with double quotes or backticks. Unsupported
-syntax fails with a parser or execution error; it is never silently ignored.
+# SQL syntax
+
+Statements are parsed by RubyDB's lexer and parser and executed through the
+planner. The supported statements include `SELECT`, `INSERT`, `UPDATE`,
+`DELETE`, table/index/schema/view DDL, transactions/savepoints, `EXPLAIN`, and
+`VACUUM` as listed in [compatibility](compatibility.md).
+
+Use semicolons for multiple statements only where the client path supports
+them. Identifiers may be quoted with double quotes or backticks. Unsupported
+syntax fails with a parser or execution error; it is never silently ignored.

data/docs/sql/transactions.md

@@ -1,10 +1,10 @@
-# SQL transactions
-
-RubyDB supports `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `ROLLBACK TO
-SAVEPOINT`, and `RELEASE SAVEPOINT`. Commits coordinate MVCC, locks, row
-mutation, WAL, and durable acknowledgement.
-
-Keep transactions short enough for the workload. Long-running readers can
-retain old versions and delay vacuum; deadlock victims must retry the
-application unit. Validate transaction behavior after restart and under
-concurrency.
+# SQL transactions
+
+RubyDB supports `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `ROLLBACK TO
+SAVEPOINT`, and `RELEASE SAVEPOINT`. Commits coordinate MVCC, locks, row
+mutation, WAL, and durable acknowledgement.
+
+Keep transactions short enough for the workload. Long-running readers can
+retain old versions and delay vacuum; deadlock victims must retry the
+application unit. Validate transaction behavior after restart and under
+concurrency.