jsonstor-couchbase

Home: http://jsonstor.liquicode.com

Version: 0.2.0

Documents are stored in a Couchbase bucket.

Overview

jsonstor defines one interface for working with a document store and implements it for a variety of database products and file formats. The interface is the same whichever adapter is underneath, so the storage a project uses becomes a configuration decision rather than a structural one.

This package is one such adapter. Documents are stored in a Couchbase bucket.

It carries no database driver. The server is reached over HTTP with the runtime's own fetch, so this package adds nothing to a project beyond jsonstor and jsongin.

See @liquicode/jsonstor for the interface, and jsonstor.liquicode.com for the documentation.

Getting Started

npm install --save @liquicode/jsonstor-couchbase

const jsonstor = require( '@liquicode/jsonstor' )();
jsonstor.LoadPlugin( require( '@liquicode/jsonstor-couchbase' ) );

let storage = jsonstor.GetStorage( 'jsonstor-couchbase', {
	Server: '...',
	Port: 8093,
	Encrypt: false,
	BucketName: '...',
	CollectionName: '...',
	PrimaryKey: "_id",
	PrimaryKeyMutable: false,
	UserName: "",
	Password: "",
} );

Versions

This package answers to more than one name. Pass any of these to GetStorage(); a name which is not listed is refused.

| Name | Dialect it uses | Measured against | |------|-----------------|------------------| | jsonstor-couchbase-v5.0 | its own | 5.0 | | jsonstor-couchbase | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v5 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v5.1 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v6 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v6.6 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v7 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v8 | jsonstor-couchbase-v5.0 | - | | jsonstor-couchbase-v8.0 | jsonstor-couchbase-v5.0 | 8.0 |

A name with its own dialect was measured against that server version and covers every later one up to the next such name. The rest resolve to one of those. The bare name follows the newest dialect this package carries, which is what most callers want.

A name whose dialect your server cannot serve is refused on the first operation, naming the version you asked for and the one the server needs.

Settings

| Setting | Required | Default | Description | |---|:---:|:---:|---| | Server | Yes | - | The name or address of the Couchbase server. | | Port | No | 8093 | The query service port. This adapter speaks to the query service and to nothing else, so no other port is needed. | | Encrypt | No | false | Reach the query service over https rather than http. There is no TrustServerCertificate beside it, because this adapter has no driver except the global fetch, which offers no supported way to relax certificate verification. | | BucketName | Yes | - | The bucket this storage reads and writes. It must already exist; this adapter never creates one. See the notes. | | CollectionName | Yes | - | The key range within the bucket which is this collection. It cannot contain a colon. See the notes. | | PrimaryKey | No | "_id" | The document field which is the identifier. String() of its value becomes the Couchbase document key. IdField is the former spelling and still works. | | PrimaryKeyMutable | No | false | Allow an update or replacement to change the identifier. When false, such an operation is refused. | | UserName | No | "" | The user to connect as. Empty means none. | | Password | No | "" | That user's password. Empty means none. |

Peculiarities

• A collection is a set of keys in a bucket. Every document key starts with <CollectionName>::, so one bucket holds many collections, and DropStorage deletes only this collection's documents. The bucket must already exist, and a CollectionName cannot contain a colon.
• The bucket needs a primary index. The adapter creates one on the first write if the user may.
• Documents are stored as written, with the identifier also used as the document key. Every document reads back exactly as written.
• Most criteria are decided by the server. The criteria becomes a N1QL WHERE clause, and the results are checked again by jsongin only for the conditions N1QL cannot decide exactly, such as $elemMatch.
• Each query waits for the index to include earlier writes, so reads see them. This costs up to about 200 ms per query. A search naming one identifier reads that document directly and does not wait.
• No driver is installed. The adapter reaches only the query service, on Port, using Node's built-in fetch, so it needs Node 18 or later.
• An https server with a self-signed certificate cannot be reached. fetch has no option to accept an untrusted certificate.

Storage Interface

Every adapter implements the same functions, and they are documented once: Storage Interface.

The operator list is not repeated here. A criteria, a projection, and an update are the engine's, and the list changes whenever the engine gains an operator - a copy in this file could only ever be out of date. See the Operator Reference.

Dependencies

• @liquicode/jsonstor : The storage interface.
• @liquicode/jsongin : The query engine.

License

MIT