A comprehensive collection of production-ready code samples demonstrating the Couchbase Python SDK 4.4.0. Learn everything from basic CRUD operations to advanced features like transactions, full-text search, and async programming.
# Clone the repository
git clone https://github.com/Fujio-Turner/cb_python_sdk_samples.git
cd cb_python_sdk_samples
# Set up virtual environment
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run your first sample
python3 01a_cb_set_get.py- Couchbase Server (local) or Capella (cloud) - Download here
- Python 3.8+
- Couchbase Python SDK 4.4.0 (auto-installed via requirements.txt)
- travel-sample bucket (load via Couchbase Web Console)
- 01a - Basic get/upsert operations
- 01b - Optimistic locking with CAS
- 02 - Upsert and delete
- 03a - SQL++ (N1QL) queries
- 03b - SQL++ query profiling
- 04 - Subdocument operations
- 05 - Exception handling + CSV/Excel import
- 06 - High availability with replica reads
- 07 - Read-your-own-writes consistency
- 08a/08b - ACID transactions (KV & Query)
- 09 - Full-text search with auto-index creation
- 10 - Debugging, logging, slow ops detection, OpenTelemetry
- 11 - Async operations with class-based design ⚡
- ai_vector_sample/ - New! Vector Search Demo (Requires Couchbase Server 8.x+)
- Create Vector Indexes (Standard & Covering)
- Perform Similarity Search (KNN)
- Compare GSI vs FTS Vector Search
- advanced_prepared_statement_wrapper.py - Query optimization
- excel_to_json_to_cb.py - Bulk data import
| Feature | Script | Highlights |
|---|---|---|
| Async/Concurrent | 11 | Class-based async client, 20 concurrent ops |
| Vector Search | ai_vector_sample/ | Semantic search, RAG, vector embeddings |
| Transactions | 08a, 08b | ACID compliance, multi-doc atomicity |
| Full-Text Search | 09 | Auto-index creation, wildcards, boolean queries |
| High Availability | 06 | Replica reads, retry logic, failover |
| Debugging | 10 | Slow ops logging, OpenTelemetry tracing |
| Error Handling | 05 | All exception types with examples |
| Performance | 11, advanced_* | Prepared statements, async, subdocs |
All scripts support local and Capella (cloud) configurations:
# Local/Self-hosted
ENDPOINT = "localhost"
cluster = Cluster(f'couchbase://{ENDPOINT}', options)
# Capella (cloud)
ENDPOINT = "cb.xxxxx.cloud.couchbase.com"
options.apply_profile('wan_development')
cluster = Cluster(f'couchbases://{ENDPOINT}', options) # Note: couchbaseS# Run all 123 unit tests
python3 run_tests.py
# Run specific test
python3 -m unittest tests.test_11_cb_async_operationsAll tests use mocking - no live Couchbase cluster required.
- 00_cb_ops_list.md - Detailed guide for all 12 sample scripts
- advanced_multi_docs.md - Batch operation patterns
- AGENTS.md - AI agent reference guide
Basic: CRUD, connections, CAS, queries
Intermediate: Subdocuments, exceptions, replicas, consistency
Advanced: Transactions, FTS, async, observability
Production: Error handling, retry logic, prepared statements, monitoring
- Max document size: 20 MB
- Max key length: 250 bytes
- Subdocument ops per request: 16
- Concurrent connections per node: 60,000
| Issue | Solution |
|---|---|
| Script hangs on connect | Use couchbase:// (not couchbases://) for local |
| Pandas slow import | Normal on M1/M2 Macs (~15s wait) |
| NetworkException error | Use ServiceUnavailableException instead |
| BucketNotFoundException | Load travel-sample bucket in Couchbase UI |
Contributions welcome! See contribution guidelines in the full documentation.
- Fork the repository
- Create feature branch
- Follow existing code patterns
- Add tests for new features
- Submit pull request
MIT License - see LICENSE
SDK Version: 4.4.0 | Python: 3.8+ | Author: Fujio Turner