Couchbase

Use the @bijection/connectors/couchbase entrypoint to declare Couchbase resources.

Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. Source build and package availability.

Resources and modes

Resource	Mode	Description
Collection keyspace	`watermark`	SQL++ watermark

Declare a resource in application code, then bind deployment-specific settings and credentials. See typed resources, connections and source inspection.

Collection keyspace

watermark: SQL++ watermark

The following example matches configuration standard.

import { couchbase } from "@bijection/connectors/couchbase";
import { v } from "bijection/values";

export const orders = couchbase.keyspace.watermark({
  schema: { status: v.string() },
  watermark: "updatedAt",
});

Inferred record types

{
  "status": string;
  "_id": string;
  "_cas": string;
}

Configuration: standard

Case: couchbase/keyspace/watermark/standard. Connection and resource configuration are declared by this exact case. Credential kind: couchbase. Keep credential material in the private credential inventory.

Setting	Type	Required	Owner
`url`	string	Yes	Shared connection
`keyspace`	string	Yes	Resource binding

Complete configuration contract

{
  "setup": [],
  "resource": {
    "access": {},
    "defaults": {},
    "connector": "couchbase",
    "output": {
      "kind": "single",
      "collection": "records"
    },
    "credential_kind": "couchbase",
    "connection_fields": [
      "url"
    ],
    "selection_field": "keyspace",
    "address": {
      "kind": "setup",
      "field": "url"
    }
  },
  "connection_setup": {
    "type": "object",
    "value": {
      "url": {
        "fieldType": {
          "type": "string"
        },
        "optional": false
      },
      "keyspace": {
        "fieldType": {
          "type": "string"
        },
        "optional": false
      }
    }
  },
  "execution": null
}

Native admission analysis is available for this exact declaration. Collection: records

Contract	Meaning
Initial	Enumeration of observed records
Changes	Repeated observations of current records
Deletions	Deletion detection unsupported
Resume	Opaque cursor
Gap	Explicit repair required after a gap
Retention	Unspecified

Complete native profile

{
  "movement": {
    "exchanges": {
      "records": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "400": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "404": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "500": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      }
    },
    "nativeInputLimitBytes": null,
    "steps": [
      {
        "id": "acquire.1",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange records",
          "limitBytes": null
        }
      },
      {
        "id": "retain.1",
        "inputs": [
          "acquire.1"
        ],
        "action": {
          "operation": "retain",
          "subject": "acquisition evidence",
          "reason": "recovery",
          "release": "acquisition_custody"
        }
      },
      {
        "id": "interpret.1",
        "inputs": [
          "retain.1"
        ],
        "action": {
          "operation": "interpret",
          "subject": "acquired input",
          "produces": "records"
        }
      },
      {
        "id": "materialize.1",
        "inputs": [
          "interpret.1"
        ],
        "action": {
          "operation": "materialize",
          "subject": "source rows",
          "reason": "serving",
          "release": "replacement"
        }
      },
      {
        "id": "publish.1",
        "inputs": [
          "materialize.1"
        ],
        "action": {
          "operation": "publish",
          "subject": "source rows",
          "visibility": "with_acquisition"
        }
      }
    ]
  },
  "initial": "enumeration",
  "changes": "observations",
  "deletions": "unsupported",
  "resume": "opaque_cursor",
  "retentionMs": null,
  "gap": "explicit_repair",
  "limits": {
    "http_response_bytes": "524288"
  },
  "restrictions": [],
  "commands": {}
}

Commands, occurrences and artifacts

{
  "records": {
    "records": {
      "protocol": "record_observation",
      "coverage": "records",
      "consistency": "observations",
      "atomicity": "record",
      "history": "observations",
      "recordRefresh": false,
      "reconciliation": false,
      "notifications": false,
      "snapshotMaxRows": null,
      "profile": {
        "movement": {
          "exchanges": {
            "records": {
              "200": {
                "placement": "retained_bytes",
                "interpretation": "json",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "400": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "401": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "403": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "404": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "500": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              },
              "503": {
                "placement": "retained_bytes",
                "interpretation": "opaque",
                "projectsBeforeRetention": false,
                "retainedBodyLimitBytes": "524288",
                "fileLimitBytes": null
              }
            }
          },
          "nativeInputLimitBytes": null,
          "steps": [
            {
              "id": "acquire.1",
              "inputs": [],
              "action": {
                "operation": "acquire",
                "subject": "exchange records",
                "limitBytes": null
              }
            },
            {
              "id": "retain.1",
              "inputs": [
                "acquire.1"
              ],
              "action": {
                "operation": "retain",
                "subject": "acquisition evidence",
                "reason": "recovery",
                "release": "acquisition_custody"
              }
            },
            {
              "id": "interpret.1",
              "inputs": [
                "retain.1"
              ],
              "action": {
                "operation": "interpret",
                "subject": "acquired input",
                "produces": "records"
              }
            },
            {
              "id": "materialize.1",
              "inputs": [
                "interpret.1"
              ],
              "action": {
                "operation": "materialize",
                "subject": "source rows",
                "reason": "serving",
                "release": "replacement"
              }
            },
            {
              "id": "publish.1",
              "inputs": [
                "materialize.1"
              ],
              "action": {
                "operation": "publish",
                "subject": "source rows",
                "visibility": "with_acquisition"
              }
            }
          ]
        },
        "initial": "enumeration",
        "changes": "observations",
        "deletions": "unsupported",
        "resume": "opaque_cursor",
        "retentionMs": null,
        "gap": "explicit_repair",
        "limits": {
          "http_response_bytes": "524288"
        },
        "restrictions": [],
        "commands": {}
      }
    }
  },
  "occurrences": null,
  "artifacts": {
    "raw_archive": false,
    "native_file_transfer_limit_bytes": null,
    "external_versions": false,
    "files": {}
  },
  "commands": {}
}

Recorded checks

Requirement	Scope	Evidence	Result
page-publication-recovery	{“kind”:“collection”,“name”:“records”}	Native test: integrations/acquisition/acquisition_windows_preserve_sequences_and_restart_fences_old_work (shared_engine)	Execution result unavailable
watermark-boundary-replay	{“kind”:“collection”,“name”:“records”}	Fixture: ./src/connectors/couchbase/fixtures/boundary-replay.json	passed (2026-10-24T21:36:12.006Z)
watermark-empty-page-ends	{“kind”:“collection”,“name”:“records”}	Fixture: ./src/connectors/couchbase/fixtures/empty-page-ends.json	passed (2026-10-24T21:36:12.006Z)
identity-account	{“kind”:“connection”}	Fixture: ./src/connectors/couchbase/fixtures/identity.json	passed (2026-10-24T21:36:12.007Z)

Hosted qualification: unestablished for this catalog configuration. Installed connections report their own identity, authority and current status.

Provider guidance

Compiled declaration examples and configuration details are published in the connector reference. Bind the Query service origin (url, for example https://host:18093) on the connection and the SQL++ keyspace path (keyspace, for example `shop`.`sales`.`orders`) on the resource. Authenticate with Basic (couchbase.credential(name)), as a Couchbase RBAC user with query select on the keyspace.

Mechanism. SQL++ through POST /query/service, not DCP: DCP is a binary protocol with no client in this workspace. Each page selects META(d).id, TOSTRING(META(d).cas) and the document where the watermark is >= $1 and < $2, ordered by the watermark then META(d).id, with scan_consistency: request_plus.
Watermark. A top-level field every writer sets on every mutation, as toISOString() UTC text, covered by a GSI index. The host keeps the largest value a page carried; the inclusive bound re-reads it, deduplicated by CAS. A full page sharing one watermark cannot advance and fails visibly.
Why not CAS as the watermark. CAS is a hybrid logical clock per vBucket: not monotonic across nodes, failover-promoted replicas or XDCR, beyond exact JSON doubles, and not fixed-width text. It is the record version only.
Settle window. $2 is now minus settleMs (default 5 s), declared as the observation lag.
Deletions. Not observed: removed and expired documents leave the result set silently, and a document without the watermark is never read.
Read-only. The Query service takes no request precondition (no CAS or If-Match), and a SQL++ UPDATE ... WHERE META(d).cas = $cas reports its verdict in body fields that HTTP 200 also carries for timeouts, so no write could be declared conditional with an exact refusal. CAS-conditioned writes need the Data service (for example through Capella’s Data API), which is not built.

Not established: no request has reached Couchbase; the exact TOSTRING rendering of a 64-bit CAS is unverified.

Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

Source and evidence

Canonical connector source, native analysis and check receipts. Connector artifact: 905888ea276a2a28e36981a79e8142b2547ea451c3e63162cb6915ad4a7d1305. The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.

Get Started

Use-case atlas

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Availability

Resources and modes

Collection keyspace

watermark: SQL++ watermark

Configuration: standard

Provider guidance

Provider references

Source and evidence

​Availability

​Resources and modes

​Collection keyspace

​watermark: SQL++ watermark

​Configuration: standard

​Provider guidance

​Provider references

​Source and evidence

Availability

Resources and modes

Collection keyspace

watermark: SQL++ watermark

Configuration: standard

Provider guidance

Provider references

Source and evidence