simply_based/README.md

SimplyBased

A Couchbase-native ActiveModel ORM — the same API as simply_couch (CouchDB), running on Couchbase via the official SDK. Swap one line:

-  include SimplyCouch::Model
+  include SimplyBased::Model

…and your models, associations, validations, callbacks and finders run on Couchbase: key/value for documents, N1QL/SQL++ + GSI for queries, CAS for optimistic concurrency. There is no CouchDB design document or JavaScript map/reduce anywhere — the hand-written association views become N1QL.

class User
  include SimplyBased::Model
  property :name
  has_many :posts
  validates :name, presence: true
end

SimplyBased.adapter ||= nil
SimplyBased.database_url =
  "couchbase://Administrator:password@localhost/app?scope=_default&collection=_default"

user = User.create(name: "Ada")   # KV insert
User.find(user.id)                # KV get
User.all                          # N1QL SELECT
User.find_by_name("Ada")          # N1QL WHERE name = $key
user.posts                        # N1QL WHERE user_id = $id (GSI auto-created)
user.post_count                   # N1QL COUNT(*)

Why it works with so little change

simply_couch's model layer (properties, type-casting, validations, callbacks, dirty tracking, the association DSL, soft-delete, pagination) is already storage -neutral. SimplyBased keeps all of it and replaces exactly one layer — the SimplyBased::Store — which speaks Couchbase directly. Every association lookup funnels through a handful of Store methods (find_by_foreign_key, find_by_array_contains, …) that emit N1QL instead of querying JS views. So the has_and_belongs_to_many join that needed two hand-written map/reduce functions in CouchDB is now:

SELECT c.*, META(c).id, META(c).cas
FROM `bucket`.`_default`.`_default` AS c
WHERE c.ruby_class = $rc
  AND ANY x IN c.`network_ids` SATISFIES x = $v END

backed by an array GSI created on first use.

Replaces Redis too

Same cluster, no second datastore:

counter = SimplyBased::Counter.new
counter.increment("jobs:processed")          # server-side atomic INCR

Rails.application.config.cache_store =
  SimplyBased::Cache.new(namespace: "app")   # ActiveSupport::Cache::Store (KV + TTL)

SimplyBased::Lock.new.with_lock("rebuild", ttl: 30) do
  # critical section — distributed lock via insert-if-absent + CAS
end

• Counter — Couchbase binary increment/decrement (true atomic counters), with Redis INCR/INCRBY semantics: the first increment of a missing key returns the delta. One divergence: Couchbase counters are unsigned, so decrement clamps at 0 instead of going negative.
• Cache — an ActiveSupport::Cache::Store over KV + native TTL; drop-in for Rails.cache and therefore ActiveJob. (clear is a no-op — entries expire via TTL.)
• Lock — distributed lock: insert-if-absent + mandatory TTL auto-expiry + CAS-checked release, so only the holder can unlock (force_release! is the explicit override) and a crashed holder can never leave an immortal lock.

The one recommended pattern shift

v0 uses a single collection with a ruby_class discriminator (closest to CouchDB, runs the whole suite as-is). For production, map each model to its own Couchbase Collection — tighter GSIs, cleaner queries, idiomatic Couchbase. A collection :name per-model DSL is the planned opt-in.

Status & test coverage

SimplyBased runs the simply_couch test suite (plus its own additions) against a live Couchbase. See SIMPLY_BASED_REVIEW.md for the full independent review this status section is based on.

• Green: CRUD, finders (find, all, first, find_by_*, count_by_*), belongs_to / has_many / has_one / has_and_belongs_to_many, validations, callbacks, dirty tracking, soft-delete (incl. soft-delete-aware finders), pagination, bulk (true batched KV multi-ops), eager-loading, embedded documents (has_many_embedded / is_embedded_in, minus reverse lookups), ancestry / trees, the Redis primitives, adapter-contract shared examples, and multi-threaded concurrency examples (CAS conflicts, atomic counters, lock mutual exclusion).
• Ancestry is a materialized path (path_ids, root→self): children = path_ids[len-2] = $id, subtree = $id IN path_ids, roots = ARRAY_LENGTH(path_ids) = 1 — plain N1QL, no recursive view build.
• Views that cannot translate to N1QL raise SimplyBased::UnsupportedView at query time (:conditions JS fragments, :emit_value, list functions) instead of silently returning unfiltered results.
• Excluded by design:
  • :couchdb_only specs — native inline attachments, JS-view token-safety, design-document maintenance, raw custom JS views: no Couchbase equivalent (use has_s3_attached / has_local_attached; N1QL uses bound parameters).
  • embedded_in reverse-lookups (:embedded_in_reverse_lookup) — querying a foreign key stored inside an embedded array element would need an UNNEST-based query path; not implemented.

Known gaps (unchanged, deliberate)

• No multi-document transactions — single-document atomicity + CAS only. Couchbase's SDK has transactions; this ORM does not surface them.
• No index-migration framework — GSIs are created lazily per association; ad-hoc queries need deliberately designed indexes or they fall back to a primary scan (a warning is emitted when lazy index creation fails).
• Cache#clear is a no-op (namespaced clear would need a key scan); entries expire via their TTLs.

docker run -d --name cb -p 8091-8096:8091-8096 -p 11210:11210 couchbase:community
# init a single-node cluster + a couchstore bucket named simply_based_test, then:
COUCHBASE_URL="couchbase://Administrator:password@localhost/simply_based_test" \
  bundle exec rspec

License

MIT.