rubydb 0.1.4 → 0.1.6

data/docs/developer/database-diff.md

@@ -1,10 +1,10 @@
-# Database diff
-
-Database diff compares schema and supported state between database snapshots or
-branches. Use it to review migration impact and branch changes before applying
-them. A diff is evidence for review, not an automatic guarantee that every
-application query remains compatible.
-
-For production changes, take a verified backup, inspect the diff, apply it to a
-staging restore with representative data, run migrations and smoke queries, and
-retain the original for rollback.
+# Database diff
+
+Database diff compares schema and supported state between database snapshots or
+branches. Use it to review migration impact and branch changes before applying
+them. A diff is evidence for review, not an automatic guarantee that every
+application query remains compatible.
+
+For production changes, take a verified backup, inspect the diff, apply it to a
+staging restore with representative data, run migrations and smoke queries, and
+retain the original for rollback.

data/docs/developer/local-development.md

@@ -1,17 +1,49 @@
-# Local development
-
-```sh
-bundle install
-bundle exec rspec
-bundle exec rubocop
-```
-
-Use `tmp/` or `Dir.mktmpdir` for databases. The server/client examples are
-appropriate when testing process boundaries. Do not open one embedded path from
-multiple processes. Use the reported fuzz seed and commit when reproducing a
-failure.
-
-Start with the [developer guide](../developer-guide.md). For failures, use a
-fresh copy, preserve WAL and metadata, run the narrowest spec first, then the
-full suite. The [debugging playbook](../debugging.md) describes safe logging,
-thread dumps, protocol isolation, and diagnostic reports.
+# Local development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Use `tmp/` or `Dir.mktmpdir` for databases. The server/client examples are
+appropriate when testing process boundaries. Do not open one embedded path from
+multiple processes. Use the reported fuzz seed and commit when reproducing a
+failure.
+
+## Bundled Go accelerator
+
+The checkout includes the Go accelerator source under `accelerator/`. Go is
+needed to build RubyDB, not to run an installed gem. The release gem contains
+the platform binary and falls back to Ruby if a platform is not packaged. To
+build the binaries from a checkout:
+
+```sh
+ruby scripts/build_accelerator
+ruby -Ilib exe/rubydb accelerator --ping --json
+```
+
+Use Ruby-only mode while diagnosing a query difference:
+
+```sh
+RUBYDB_ACCELERATOR=off bundle exec rspec spec/sql_compatibility_spec.rb
+```
+
+The default `auto` mode uses the binary columnar protocol, checks result
+equivalence against Ruby on the first eligible scan/aggregate/join, and keeps
+Go only when it is faster. Use required mode in a controlled integration test
+to ensure a deployment has the expected binary:
+
+```yaml
+accelerator:
+  mode: required
+  min_rows: 0
+```
+
+The Go worker is private to its Ruby parent. It is not a database server and
+does not make an embedded file safe to open from multiple processes.
+
+Start with the [developer guide](../developer-guide.md). For failures, use a
+fresh copy, preserve WAL and metadata, run the narrowest spec first, then the
+full suite. The [debugging playbook](../debugging.md) describes safe logging,
+thread dumps, protocol isolation, and diagnostic reports.

data/docs/developer/snapshots.md

@@ -1,9 +1,9 @@
-# Snapshots
-
-Snapshots capture a consistent RubyDB state for inspection, backup validation,
-branching, or staging. Create snapshots through the supported CLI/API and keep
-the snapshot with its metadata and checksum.
-
-Validate a snapshot by opening it in a separate directory. Do not treat a
-snapshot as a replacement for an independently verified backup or replication.
-Keep retention and deletion policies explicit for production data.
+# Snapshots
+
+Snapshots capture a consistent RubyDB state for inspection, backup validation,
+branching, or staging. Create snapshots through the supported CLI/API and keep
+the snapshot with its metadata and checksum.
+
+Validate a snapshot by opening it in a separate directory. Do not treat a
+snapshot as a replacement for an independently verified backup or replication.
+Keep retention and deletion policies explicit for production data.

data/docs/developer/temporal-data.md

@@ -1,10 +1,10 @@
-# Temporal data
-
-MVCC keeps row versions long enough for active transaction visibility and safe
-vacuum. Readers observe a transaction-consistent view according to the selected
-isolation behavior; uncommitted changes are not published to other readers.
-
-Long-running transactions retain old versions and can increase storage. Monitor
-transaction age and vacuum/compaction duration, and terminate or redesign stale
-work before it affects the workload. Test temporal behavior with restart and
-rollback, not only a single read.
+# Temporal data
+
+MVCC keeps row versions long enough for active transaction visibility and safe
+vacuum. Readers observe a transaction-consistent view according to the selected
+isolation behavior; uncommitted changes are not published to other readers.
+
+Long-running transactions retain old versions and can increase storage. Monitor
+transaction age and vacuum/compaction duration, and terminate or redesign stale
+work before it affects the workload. Test temporal behavior with restart and
+rollback, not only a single read.