n8n-nodes-couchdb

A community node for n8n that provides integration with Apache CouchDB and CloudStation.

Disclaimer: This is an independent community project and is not affiliated with, officially maintained, endorsed, or sponsored by the Apache Software Foundation or the Apache CouchDB project. Apache CouchDB and CouchDB are trademarks of the Apache Software Foundation.

Features

• CRUD Operations: Create, Read, Update, and Delete documents
• Mango Queries: Use CouchDB's powerful query language with the Find operation
• Real-time Triggers: Monitor database changes with polling triggers
• CloudStation Compatible: Works with CloudStation databases
• Relational-Pouch Support: Uses {model}_2_{UUID} ID format for compatibility with relational-pouch
• Raw Mode: Direct CouchDB access for non Relational-Pouch databases (e.g., _users)
• Anonymous Access: Supports CouchDB instances without authentication (username/password optional)

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-couchdb and click Install

Manual Installation

npm install n8n-nodes-couchdb

Credentials

Before using the CouchDB nodes, configure your credentials:

| Field | Description | Required | Example | |-------|-------------|----------|---------| | Host | CouchDB server URL | Yes | http://localhost:5984 | | Database | Database name | Yes | my_database | | Username | Authentication username | No | admin | | Password | Authentication password | No | ******** |

Anonymous Access

For CouchDB instances configured to allow anonymous access, leave the Username and Password fields empty. The node will connect without authentication.

CloudStation Configuration

For CloudStation databases, use:

• Host: https://my.cloudstation.com
• Database: Your CloudStation database name (e.g., bloggr)

CouchDB Node

The main node for document operations.

Operation Modes

The node supports two operation modes:

| Mode | Description | |------|-------------| | Standard Mode (default) | Relational-Pouch compatible. Auto-generates IDs as {modelName}_2_{UUID}, stores data under data field. | | Raw Mode | Direct CouchDB access. Custom document IDs, data stored directly without wrapper. Useful for _users database or non Relational-Pouch structured databases. |

Toggle Raw Mode at the top of the node configuration to switch between modes.

Operations

Create

Creates a new document in the database.

Standard Mode

Parameters:

• Model Name: The model prefix for the document ID (e.g., post, author)
• Data: JSON data to store under the data field

Example Input:

{
  "title": "My First Post",
  "content": "Hello, World!",
  "createdAt": "2026-01-14T10:00:00Z"
}

Example Output:

{
  "_id": "post_2_085B3329-6C91-8FDE-A397-4CC088ADE594",
  "_rev": "1-abc123def456",
  "ok": true,
  "data": {
    "title": "My First Post",
    "content": "Hello, World!",
    "createdAt": "2026-01-14T10:00:00Z"
  }
}

Raw Mode

Parameters:

• Document ID: Custom document ID (e.g., org.couchdb.user:martin)
• Data: JSON data stored directly as document body

Example Input:

{
  "name": "martin",
  "type": "user",
  "roles": ["editor"]
}

Example Output:

{
  "_id": "org.couchdb.user:martin",
  "_rev": "1-abc123def456",
  "ok": true,
  "data": {
    "name": "martin",
    "type": "user",
    "roles": ["editor"]
  }
}

Get

Retrieves a document by its ID.

Parameters:

• Document ID: The full document ID (e.g., post_2_085B3329-6C91-8FDE-A397-4CC088ADE594)

Get All

Lists all documents in the database.

Options:

• Limit: Maximum number of documents (default: 100)
• Skip: Number of documents to skip
• Include Docs: Include full document content
• Start Key / End Key: Pagination keys

Update

Updates an existing document.

Parameters:

• Document ID: The document to update
• Document Revision: Optional. If empty, fetched automatically
• Data: New data for the document

Delete

Removes a document from the database.

Parameters:

• Document ID: The document to delete
• Document Revision: Optional. If empty, fetched automatically

Find

Queries documents using Mango selectors.

Parameters:

• Selector: Mango query selector

Example Selector:

{
  "data.title": { "$eq": "My First Post" }
}

Options:

• Limit: Maximum results
• Skip: Skip count
• Sort: Sort order (e.g., [{"data.createdAt": "desc"}])
• Fields: Comma-separated list of fields to return
• Use Index: Specify which index to use for the query. Can be an array like ["design-doc", "index-name"] or a string like "design-doc/index-name"

CouchDB Trigger

Monitors database changes in real-time using polling.

Events

| Event | Description | |-------|-------------| | Document Changed | Triggers on any document change | | Document Created | Triggers only for new documents | | Document Updated | Triggers only for updates to existing documents | | Document Deleted | Triggers only when documents are deleted |

Options

| Option | Description | |--------|-------------| | Document IDs | Comma-separated list of specific document IDs to watch | | Filter by Model | Only trigger for documents with a specific model prefix | | Include Design Docs | Whether to include design document changes | | Limit | Maximum number of changes per poll (default: 100, 0 = unlimited) | | Selector | Mango selector to filter changes | | Since | Where to start reading changes from (see below) | | Custom Sequence Value | Specific sequence number (only when Since = Custom) |

Since Parameter

Controls where the trigger starts reading changes from. This is important for workflow activation/publish behavior.

| Option | Value | Description | |--------|-------|-------------| | Last Saved Sequence | last | Default. Continues from last processed sequence. Remembers where it left off between polls. Falls back to beginning (0) on first run or after workflow activation. | | Now (Skip History) | now | Starts from current point, ignoring all historical changes. Recommended for production. | | Custom Sequence | custom | Specify a custom sequence number to start from. |

Workflow Publish Behavior

When a workflow is published/activated in n8n, the static data (including last sequence) is reset. This causes the trigger to restart from the beginning by default.

Solution: Set Since to Now (Skip History) for production workflows. This ensures only new changes are processed after each workflow publish.

Recommended Production Settings

Options:
  Since: Now (Skip History)
  Limit: 100

This configuration ensures:

• No reprocessing of historical data on workflow publish
• Controlled batch sizes for predictable performance

Example Output

{
  "_id": "post_2_085B3329-6C91-8FDE-A397-4CC088ADE594",
  "_seq": "123-abc",
  "_changes": [{ "rev": "2-def456" }],
  "_deleted": false,
  "_isNew": false,
  "document": {
    "_id": "post_2_085B3329-6C91-8FDE-A397-4CC088ADE594",
    "_rev": "2-def456",
    "data": {
      "title": "Updated Post",
      "content": "Updated content"
    }
  }
}

Document Structure

Standard Mode (Relational-Pouch)

Documents follow the relational-pouch structure:

{
  "_id": "{model}_2_{UUID}",
  "_rev": "1-abc123",
  "data": {
    // Your data here
  }
}

ID Format:

• Format: {model_name}_2_{UUID}
• The _2_ suffix indicates a string-type ID (always used per project requirements)
• Example: post_2_085B3329-6C91-8FDE-A397-4CC088ADE594

Raw Mode

Documents are stored directly without any wrapper:

{
  "_id": "custom-document-id",
  "_rev": "1-abc123",
  "field1": "value1",
  "field2": "value2"
}

Use Cases:

• Accessing non Relational-Pouch structured databases
• Custom document ID requirements

Example Workflows

Create and Query Posts

1. HTTP Trigger → Receives new post data
2. CouchDB Create → Creates document with post model
3. CouchDB Find → Queries all posts by author

Sync on Changes

1. CouchDB Trigger → Monitors for document changes
2. IF Node → Filters by document type
3. HTTP Request → Sends webhook notification

Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes
npm run dev

# Run linting
npm run lint

# Deploy to Docker environment
npm run deploy

Resources

• CouchDB Documentation
• CouchDB HTTP API
• CloudStation
• n8n Community Nodes
• Relational Pouch

License

MIT - Martinic

Author

Mehmet Burak Akgün ([email protected])

Trademarks

Apache, Apache CouchDB, CouchDB, and the CouchDB logo are trademarks or registered trademarks of the Apache Software Foundation in the United States and/or other countries. This project is not endorsed by or affiliated with the Apache Software Foundation.