{"id":30363822,"url":"https://github.com/deans-bradley/couch-bridge","last_synced_at":"2026-06-28T05:31:53.846Z","repository":{"id":307668084,"uuid":"1030286490","full_name":"deans-bradley/couch-bridge","owner":"deans-bradley","description":"A powerful Node.js CLI tool for efficient CouchDB operations including bulk inserts, deletes, and document queries.","archived":false,"fork":false,"pushed_at":"2026-05-25T17:00:29.000Z","size":78,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T18:27:02.329Z","etag":null,"topics":["cli","commanderjs","console","couchdb","database"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deans-bradley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-01T11:39:45.000Z","updated_at":"2026-05-25T16:59:40.000Z","dependencies_parsed_at":"2025-08-01T14:38:45.127Z","dependency_job_id":"4b702750-699b-47b9-8a6a-22463da6eeae","html_url":"https://github.com/deans-bradley/couch-bridge","commit_stats":null,"previous_names":["deans-bradley/couch-bridge"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/deans-bradley/couch-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Fcouch-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Fcouch-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Fcouch-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Fcouch-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deans-bradley","download_url":"https://codeload.github.com/deans-bradley/couch-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Fcouch-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34878963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","commanderjs","console","couchdb","database"],"created_at":"2025-08-19T19:50:57.707Z","updated_at":"2026-06-28T05:31:53.841Z","avatar_url":"https://github.com/deans-bradley.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CouchBridge\n\nA powerful Node.js CLI tool for efficient CouchDB operations including bulk inserts, deletes, and document queries.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-\u003e=22.14.0-green.svg)](https://nodejs.org/)\n[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/deans-bradley/couch-bridge)\n\n## Features\n\n- **Bulk Insert Operations** - Uses CouchDB's `_bulk_docs` endpoint for maximum performance\n- **Bulk Delete Operations** - Efficiently delete documents by view queries\n- **Document Querying** - Filter and analyze documents by property values\n- **Smart Batching** - Automatically splits large datasets into manageable batches\n- **Database Selection** - Work with any database, with configurable defaults\n- **Detailed Progress Tracking** - Batch-by-batch progress with success/failure counts\n- **View Integration** - Leverage CouchDB views for efficient queries and operations\n\n## Installation\n\n### Setup\n\n1. Clone or download CouchBridge\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Make the CLI globally accessible:\n   ```bash\n   npm install -g .\n   ```\n\n4. Configure your CouchDB connection (see Configuration section below)\n\n## Configuration\n\nCouchBridge stores CLI-managed settings in a JSON file at:\n\n- Windows: `%LOCALAPPDATA%\\couch-bridge\\config.json`\n- macOS/Linux: `~/.config/couch-bridge/config.json`\n\nYou can create or update config values with the new `config` command.\n\n**Configuration options:**\n- `CouchUrl` - Your CouchDB server URL\n- `DefaultDatabase` - Default CouchDB database name\n- `CouchUsername` - CouchDB username for authentication\n- `CouchPassword` - CouchDB password for authentication\n\nUse the CLI command:\n\n```bash\ncb config --couch-url http://localhost:5984 \\\n  --default-database your_default_database \\\n  --couch-username admin \\\n  --couch-password your_password\n```\n\nTo view current settings:\n\n```bash\ncb config --show\n```\n\n## Usage\n\n### Document Insert Operations\n\n#### Basic Upload\nUpload documents from a JSON file to your default database:\n```bash\ncb insert documents.json\n```\n\n#### Upload to Specific Database\n```bash\ncb insert documents.json --database my_other_db\ncb insert documents.json -d production_data\n```\n\n#### Custom Batch Size\nAdjust batch size for performance tuning or memory constraints:\n```bash\n# Larger batches for better performance (default: 100)\ncb insert large-dataset.json --batch-size 500\n\n# Smaller batches for memory-constrained environments\ncb insert documents.json -b 25\n```\n\n### Document Delete Operations\n\n#### Delete by View\nDelete documents using CouchDB views:\n```bash\n# Delete documents from a view\ncb delete design_doc/view_name\n\n# Delete with specific key\ncb delete design_doc/view_name --key \"user123\"\n\n# Custom batch size and database\ncb delete design_doc/view_name -k \"user123\" -d my_db -b 50\n```\n\n### Document Query Operations\n\n#### Query by Property Value\nFilter and analyze documents by property values:\n```bash\n# Show all documents with a specific property value\ncb where design_doc/view_name status --value \"active\"\n\n# Show value distribution for a property (no --value specified)\ncb where design_doc/view_name status\n\n# Query with specific view key\ncb where design_doc/view_name status --key \"user123\" --value \"active\"\n```\n\n### Combined Options Examples\n\n```bash\n# Insert with custom settings\ncb insert data.json -d test_db -b 200\n\n# Delete with custom settings  \ncb delete user_docs/by_status -k \"inactive\" -d user_db -b 100\n\n# Query specific database\ncb where user_docs/by_status status -d production_db\n```\n\n## Input Format\n\nYour JSON file should contain an array of documents:\n\n```json\n[\n  {\n    \"_id\": \"doc1\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\",\n    \"age\": 30\n  },\n  {\n    \"_id\": \"doc2\", \n    \"name\": \"Jane Smith\",\n    \"email\": \"jane@example.com\",\n    \"age\": 25\n  }\n]\n```\n\n**Notes:**\n- Documents can include `_id` fields or let CouchDB auto-generate them\n- Each document can have any valid JSON structure\n- Large files are automatically processed in batches\n\n## Command Reference\n\n### `cb insert`\n\nUpload documents to CouchDB using bulk operations.\n\n**Syntax:**\n```bash\ncb insert \u003cinput\u003e [options]\n```\n\n**Arguments:**\n- `\u003cinput\u003e` - Path to JSON file containing an array of documents\n\n**Options:**\n- `-b, --batch-size \u003csize\u003e` - Number of documents per batch (default: 100)\n- `-d, --database \u003cname\u003e` - Target database name (uses config default if not specified)\n- `-h, --help` - Display help for command\n\n**Examples:**\n```bash\n# Basic upload\ncb insert data.json\n\n# Custom batch size\ncb insert data.json --batch-size 250\n\n# Specific database\ncb insert data.json --database production_db\n\n# Combined options\ncb insert large-file.json -d test_db -b 500\n```\n\n### `cb delete`\n\nDelete documents from CouchDB using view queries with bulk operations.\n\n**Syntax:**\n```bash\ncb delete \u003cview\u003e [options]\n```\n\n**Arguments:**\n- `\u003cview\u003e` - View name in format \"design_doc/view_name\"\n\n**Options:**\n- `-k, --key \u003ckey\u003e` - The key value to query the view\n- `-d, --database \u003cname\u003e` - Target database name (uses config default if not specified)\n- `-b, --batch \u003csize\u003e` - Number of documents per batch (default: 100)\n- `-h, --help` - Display help for command\n\n**Examples:**\n```bash\n# Delete all documents from a view\ncb delete user_docs/by_status\n\n# Delete documents with specific key\ncb delete user_docs/by_status --key \"inactive\"\n\n# Custom batch size and database\ncb delete user_docs/by_status -k \"expired\" -d cleanup_db -b 50\n```\n\n### `cb where`\n\nFilter and analyze documents by property values using CouchDB views.\n\n**Syntax:**\n```bash\ncb where \u003cview\u003e \u003cproperty\u003e [options]\n```\n\n**Arguments:**\n- `\u003cview\u003e` - View name in format \"design_doc/view_name\"\n- `\u003cproperty\u003e` - The property name to filter by\n\n**Options:**\n- `-k, --key \u003ckey\u003e` - The key value to query the view\n- `-v, --value \u003cvalue\u003e` - The property value to filter by (omit to see value distribution)\n- `-d, --database \u003cname\u003e` - Target database name (uses config default if not specified)\n- `-h, --help` - Display help for command\n\n**Examples:**\n```bash\n# Show value distribution for a property\ncb where user_docs/all status\n\n# Filter documents by specific property value\ncb where user_docs/all status --value \"active\"\n\n# Query with specific view key\ncb where user_docs/by_region status --key \"us-east\" --value \"active\"\n\n# Query specific database\ncb where user_docs/all status -d production_db\n```\n\n## Output Examples\n\n### Successful Insert Operation\n\n```\nStarting bulk upload of 350 documents (batch size: 100) to database: my_database...\nProcessing 4 batch(es)...\n\nProcessing batch 1/4 (100 documents)...\n✓ Batch 1: 100 successful\n\nProcessing batch 2/4 (100 documents)...\n✓ Batch 2: 100 successful\n\nProcessing batch 3/4 (100 documents)...\n✓ Batch 3: 98 successful, 2 failed\n  Errors in batch 3:\n    - Document 250: conflict (Document update conflict)\n    - Document 263: bad_request (Invalid document ID)\n\nProcessing batch 4/4 (50 documents)...\n✓ Batch 4: 50 successful\n\nUpload Summary:\n  Total documents: 350\n  Successful: 348\n  Failed: 2\n  Success rate: 99.4%\n\n2 errors occurred during upload\n```\n\n### Delete Operation Output\n\n```\nQuerying view: user_docs/by_status with key: inactive\nFound 45 documents to delete\nProcessing deletion in 1 batch(es) of size 100...\n\nProcessing batch 1/1 (45 documents)...\n✓ Batch 1: 43 successful, 2 failed\n  Errors in batch 1:\n    - Document user_123: conflict (Document update conflict)\n    - Document user_456: not_found (Document not found)\n\nDeletion Summary:\n  Total documents: 45\n  Successful: 43\n  Failed: 2\n  Success rate: 95.6%\n```\n\n### Where Query Output\n\n```\n# Value distribution query\n✓ Successfully queried 1,250 documents from view user_docs/all\n\nValue distribution for property 'status':\n  active: 892 document(s)\n  inactive: 234 document(s)\n  pending: 98 document(s)\n  null: 26 document(s)\n\nSummary:\n  Total documents: 1,250\n  Unique values: 4\n\n# Filtered query\n✓ Found 892 documents where 'status' = 'active'\n\nDocuments where 'status' = 'active':\n1. user_001\n2. user_003\n3. user_007\n... (showing first 3 of 892 matches)\n```\n\n## Performance Guidelines\n\n### Batch Size Recommendations\n- **Small files (\u003c 1,000 docs)**: Use default batch size (100)\n- **Medium files (1,000 - 10,000 docs)**: Increase to 250-500\n- **Large files (\u003e 10,000 docs)**: Use 500-1,000 for optimal performance\n- **Memory constrained**: Reduce to 25-50\n\n### Performance Benefits\n- **Individual uploads**: ~10-50 docs/second\n- **Bulk uploads**: ~1,000-5,000 docs/second (depending on document size)\n- **Network efficiency**: Reduces HTTP overhead by up to 100x\n\n## Troubleshooting\n\n### Common Issues\n\n**Connection Refused**\n```bash\nError: connect ECONNREFUSED 127.0.0.1:5984\n```\n- Check that CouchDB is running\n- Verify the URL in your config\n- Ensure firewall allows connections\n\n**Authentication Failed**\n```bash\nError: Name or password is incorrect\n```\n- Verify username/password in config\n- Check that the user has appropriate permissions\n\n**Database Not Found**\n```bash\nError: Database does not exist\n```\n- Create the database first, or\n- Check database name spelling\n- Verify user has access to the database\n\n**View Not Found**\n```bash\nError: View does not exist\n```\n- Ensure the design document exists\n- Check view name format: \"design_doc/view_name\"\n- Verify the view is properly defined in the design document\n\n**Memory Issues with Large Operations**\n```bash\nError: JavaScript heap out of memory\n```\n- Reduce batch size: `cb insert file.json -b 50`\n- Use smaller batch sizes for delete operations: `cb delete view -b 25`\n- Process operations in smaller chunks\n\n**No Documents Found**\n```bash\nError: No documents found matching criteria\n```\n- Verify the view key exists\n- Check that documents exist for the specified property value\n- Ensure the view emits the expected data\n\n## Dependencies\n\n- **commander** - CLI framework and command parsing\n- **nano** - CouchDB client library\n- **chalk** - Colored console output and formatting\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Commit your changes: `git commit -am 'Add feature'`\n4. Push to the branch: `git push origin feature-name`\n5. Submit a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeans-bradley%2Fcouch-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeans-bradley%2Fcouch-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeans-bradley%2Fcouch-bridge/lists"}