Service: CouchDB - EyevinnOSC/community GitHub Wiki

CouchDB

Apache CouchDB (serviceId apache-couchdb) is a NoSQL document database. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 20 GiB of storage per instance. License: Apache-2.0. Source: apache/couchdb.

What it can do

  • Store, retrieve and sync JSON documents over an HTTP API.
  • Serve as the document database for your applications using any CouchDB client (for example the JavaScript library nano).
  • Provide the built-in CouchDB web interface for creating databases and documents and configuring CORS.

Creating an instance

Create the admin password as a service secret first: create-service-secret with serviceId: "apache-couchdb", a secret name (for example adminpassword) and the password as value. Then call create-service-instance with serviceId: "apache-couchdb". The instance name must be alphanumeric and at most 20 characters. CouchDB has no dependencies on other OSC services.

{ "name": "guide", "AdminPassword": "{{secrets.adminpassword}}" }

Wait with wait-for-service-ready (or get-instance-status), then use describe-service-instance to read the instance URL and connection details.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
AdminPassword Yes string, sensitive Password for the CouchDB administrator user admin. The catalog marks this option as one OSC can generate. To choose it yourself, store it as a service secret and pass {{secrets.NAME}}.

A {{secrets.NAME}} reference must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Access the database

Open the instance URL and log in as admin with the administrator password. Create a database (for example guide) and documents in the UI, or via the HTTP API. The connection URL has the form https://admin:<password>@<tenant>-<name>.apache-couchdb.auto.prod-se.osaas.io/guide.

When you retrieve connection details with describe-service-instance, the returned connection string contains a /DBNAME placeholder, for example https://admin:<password>@...osaas.io/DBNAME. Replace DBNAME with your actual database name (for example /guide) before using the URL in your application or passing it to another service.

Example with the JavaScript library nano:

const url = new URL('https://<tenant>-guide.apache-couchdb.auto.prod-se.osaas.io');
url.password = '<password>';
url.username = 'admin';
const client = nano(url.toString());
const db = client.db.use('guide');
await db.insert({
  title: 'Getting started with NoSQL in Eyevinn OSC',
  content: 'Learn the basics of NoSQL in Eyevinn OSC',
  createdAt: new Date()
});

Adding CORS

In the CouchDB web interface, press the gear icon in the navigation bar and select "CORS" in the Configuration menu. Press "Enable CORS" if it is not already enabled, then enter the domains your database should accept requests from.

Resources

⚠️ **GitHub.com Fallback** ⚠️