couchdex.mk

A Makefile-based CLI tool for managing CouchDB design documents. Simplifies pulling, pushing, building, and managing CouchDB design documents from a local directory structure. The directory structure integrates with git. This tool can be included as part of the user's Makefile environment or as a drop-in-replacement for couchapp.

Requirements

Before using couchdex.mk, ensure you have the following tools installed:

• make - GNU Make
• curl - For HTTP requests to CouchDB
• jq - JSON processor

On Debian/Ubuntu systems:

sudo apt-get install make curl jq

Installation

Option 1: Clone the Repository

git clone https://github.com/sklassen/couchdex
cd couchdex.mk

Option 2: Download Directly

curl -o couchdex.mk https://raw.githubusercontent.com/sklassen/couchdex/main/couchdex.mk

Option 3: Install System-Wide

To make couchdex.mk available system-wide:

sudo cp couchdex.mk /usr/local/include/

Or add it to your project's include path.

Recommended Directory Structure

couchdex.mk works best with the following directory organization:

$HOME/
├── .couchdexrc                 # Global configuration file (optional)
└── cdb/                        # Root directory for all CouchDB projects
    └── dbname/                 # Database name
        └── designname/         # Design document name
            ├── Makefile        # Project configuration (generated by init)
            ├── language        # Language setting (javascript/erlang)
            ├── views/          # View definitions
            ├── shows/          # Show functions
            ├── lists/          # List functions
            ├── updates/        # Update functions
            └── filters/        # Filter functions

This structure allows couchdex.mk to automatically infer:

• Database name from the parent directory (e.g., testdb)
• Design document name from the current directory (e.g., myapp, products, users)

Is not specified the language is javascript. The language is erlang is also supported.

Configuration

Environment Variables

Configure CouchDB connection settings via environment variables or a ~/.couchdexrc file:

COUCH_SCHEME=http          # http or https (default: http)
COUCH_HOST=127.0.0.1       # CouchDB host (default: 127.0.0.1)
COUCH_PORT=5984            # CouchDB port (default: 5984)
COUCH_ADMIN=admin          # Admin username (default: admin)
COUCH_PASSWD=secret        # Admin password (required)
COUCH_DB=mydb              # Database name (auto-detected from parent dir)
COUCH_DESIGN=mydesign      # Design document name (auto-detected from current dir)

Creating a ~/.couchdexrc File (Optional)

For convenience, create a ~/.couchdexrc file with your default settings:

COUCH_ADMIN=admin
COUCH_PASSWD=your_password

This file will be automatically loaded by couchdex.mk, so you don't need to specify credentials in each project's Makefile.

Quick Start

Initialize a New Design Document

# Create the recommended directory structure
mkdir -p ~/cdb/testdb/mydesign
cd ~/cdb/testdb/mydesign

# Initialize - this generates a Makefile with auto-detected settings
make -f couchdex.mk init

The init target generates a Makefile in the current directory with database and design names auto-detected from your directory path. After initialization, you can simply run:

make [target]

Clone an Existing Design Document

To pull an existing design document from CouchDB and create the local file structure:

# Create directory structure
mkdir -p ~/cdb/testdb/mydesign
cd ~/cdb/testdb/mydesign

# Clone (auto-detects testdb as COUCH_DB and mydesign as COUCH_DESIGN)
make -f couchdex.mk clone COUCH_PASSWD=secret

This will:

• Download the design document from CouchDB
• Create local files for views, shows, lists, updates, filters, etc.
• Extract the language setting
• Generate a Makefile for the project

Usage

Available Targets

Information & Help:

• help - Display available commands
• version - Show couchdex.mk version
• status - Show current design document status
• check - Confirm couchdex.mk is installed correctly

Server & Database Management:

• dbs - List all databases on the server
• create - Create a new database
• security - View database security settings
• compactdb - Compact the database
• cleanup - Run view cleanup

Design Document Management:

• init - Generate a Makefile with auto-detected database and design names
• fetch - Fetch (GET) the design document from CouchDB
• pull - Expands the design document into the file system
• push - Push (PUT) the design document to CouchDB
• push-force - Force push (overwrite) the design document
• clone - Clone design document and create local file structure
• build - Build the design document JSON from local files
• revs - Show revision history
• keys - Show all keys in the design document

Utility:

• compact - Compact a specific view
• clean - Remove generated files

Common Workflows

Create a New Design Document

# Create the recommended directory structure
mkdir -p ~/cdb/store/catalog
cd ~/cdb/store/catalog

# Initialize - generates Makefile (auto-detects store as DB, catalog as design doc)
make -f /usr/local/include/couchdex.mk init

# Edit the generated Makefile to add your COUCH_PASSWD (or use ~/.couchdexrc)

# Create your views and functions
mkdir -p views/by_category
echo 'function(doc) { emit(doc.category, null); }' > views/by_category/map.js

# Build and push to CouchDB
make push

Update an Existing Design Document

# Navigate to your design document directory
cd ~/cdb/testdb/mydesign

# Pull the current version
make pull

# Clone to local file structure (if not already done)
make clone

# Edit your views/functions
vim views/by_name/map.js

# Push changes back to CouchDB
make push

Work with Multiple Databases

You can override settings per command:

make push COUCH_DB=production COUCH_PASSWD=prod_secret
make pull COUCH_DB=development COUCH_PASSWD=dev_secret

Or explicitly specify when not using the recommended structure:

make push COUCH_DB=mydb COUCH_DESIGN=mydesign COUCH_PASSWD=secret

Design Document File Structure

Once initialized or cloned, your design document directory will contain:

~/cdb/dbname/designname/
├── Makefile                    # Generated by init (project configuration)
├── .design_<name>.json         # Design document cache
├── language                    # Language setting (javascript/erlang)
├── validate_doc_update.js      # Validation function (if present)
├── rewrite.js                  # Rewrite rules (if present)
├── views/                      # View definitions
│   └── by_name/
│       ├── map.js              # Map function
│       └── reduce.js           # Reduce function (optional)
├── shows/                      # Show functions
│   └── item.js
├── lists/                      # List functions
│   └── items.js
├── updates/                    # Update functions
│   └── item.js
└── filters/                    # Filter functions
    └── recent.js

Advanced Usage

Using a Shell Alias

For convenience, create an alias:

alias couchdex='make -f /usr/local/include/couchdex.mk'

Then use:

couchdex status
couchdex push

As an added convience you can also enable bash completion by adding the following snippet to your .bashrc file.

# Enable bash completion for make targets
_couchdex_targets() {
    local cur prev words cword
    _init_completion || return

    # Use grep to find targets and format them for bash completion
    COMPREPLY=($(compgen -W "$(grep -oE '^[a-zA-Z0-9_-]+:' /usr/local/include/couchdex.mk | sed 's/://')" -- "$cur"))
}
complete -F _couchdex_targets couchdex

Verbose Mode

Enable verbose output to see all commands being executed:

make push COUCH_VERBOSE=1

Force Push

If you need to overwrite remote changes (use with caution):

make push-force

Example Makefile

After running make -f couchdex.mk init in ~/cdb/testdb/mydesign/, a Makefile will be generated that looks like this:

COUCH_ADMIN=admin
#COUCH_PASSWD=PASSWD_HERE
COUCH_DB=testdb
COUCH_DESIGN=mydesign

include /usr/local/include/couchdex.mk

The init target automatically generates this file with COUCH_DB and COUCH_DESIGN values detected from your directory path. Edit this file to configure your project-specific settings, or use ~/.couchdexrc for global credentials.

Complete Example

Here's a complete workflow from start to finish:

# 1. Install couchdex.mk system-wide
sudo cp couchdex.mk /usr/local/include/

# 2. Create global configuration file
cat > ~/.couchdexrc << 'EOF'
COUCH_ADMIN=admin
COUCH_PASSWD=your_password
COUCH_HOST=127.0.0.1
COUCH_PORT=5984
EOF

# 3. Create an alias for convenience
echo "alias couchdex='make -f /usr/local/include/couchdex.mk'" >> ~/.bashrc
source ~/.bashrc

# 4. Create your CouchDB project structure
mkdir -p ~/cdb/store/products
cd ~/cdb/store/products

# 5. Initialize the project - this generates a Makefile
couchdex init

# 6. Create a view
mkdir -p views/by_price
cat > views/by_price/map.js << 'EOF'
function(doc) {
  if (doc.type === 'product' && doc.price) {
    emit(doc.price, doc.name);
  }
}
EOF

# 7. Push to CouchDB
make push

# 8. Check status
make status

Troubleshooting

Error: "COUCH_PASSWD is not set"

• Ensure you've set the COUCH_PASSWD variable in your Makefile or environment

Error: "No jq in PATH"

• Install jq: sudo apt-get install jq

Error: "No curl in PATH"

• Install curl: sudo apt-get install curl

Connection refused

• Check that CouchDB is running: curl http://127.0.0.1:5984/
• Verify your COUCH_HOST and COUCH_PORT settings

Wrong database or design document detected

• Verify you're in the correct directory structure: ~/cdb/dbname/designname/
• Or explicitly specify: make push COUCH_DB=testdb COUCH_DESIGN=mydesign

Want to see what init generates?

• Run make -f couchdex.mk init in your design document directory
• A Makefile will be created with auto-detected settings from your path

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please submit issues and pull requests on GitHub.