Couchbase Server Quickstart with Couchbase Python SDK

    +
    Using the Couchbase Python SDK, create new database records in Couchbase and look them up.

    This exercise assumes that you are familiar with relational and document databases, and provides a fast-track from zero to secondary lookup using Couchbase Server and Python SDK.

    Prerequisite: Run Couchbase Server

    1. Couchbase Server 6.5 is already running.

    2. An empty bucket named "default" has been created.

    3. Both a primary index and an adaptive index have been created and built on the default bucket.

    If you still need to perform these tasks please use the following:

    The Couchbase Python SDK 3.0 requires Python 3, with Python 3.5 and above supported

    Step 1: Install Couchbase Python SDK

    • Debian and Ubuntu

    • RHEL and CentOS

    • macOS

    # Only needed during first-time setup:
    sudo apt-get install git-all python3-dev python3-pip python3-setuptools cmake build-essential
    sudo pip3 install couchbase
    # Only needed during first-time setup:
    sudo yum install gcc gcc-c++ python-devel python-pip cmake
    sudo pip3 install couchbase
    brew update # get list of latest packages
    brew install python
    pip3 install couchbase

    For more details on installing Couchbase Python SDK 3.0, see the Couchbase Python SDK documentation.

    Step 2: Connecting to Couchbase using Python SDK

    Let’s first show how to connect with Couchbase so you can access the 'default' bucket using the Python SDK.

    # these modules are used to access and authenticate with your database cluster:
    from couchbase.cluster import Cluster, ClusterOptions, QueryOptions
    from couchbase_core.cluster import PasswordAuthenticator
    
    # specify the cluster and specify an authenticator containing a username and password to be passed to the cluster.
    
    cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('Administrator', 'password')))
    
    # following a successful authentication, a bucket can be opened.
    # access a bucket in that cluster
    
    bucket = cluster.bucket('default')
    coll = bucket.default_collection()

    Step 3: Create and Query a New Document

    Suppose we need to store the following data in the database representing 3 distinct users:

    user0001 = {
        "firstName" : "Perry",
        "lastName" : "Mason",
        "email" : "perry.mason@acme.com",
        "tagLine" : "Who can we get on the case?",
        "type" : "user"
    }
    
    user0002 = {
        "firstName" : "Major",
        "lastName" : "Tom",
        "email" : "major.tom@acme.com(opens in new tab)",
        "tagLine" : "Send me up a drink",
        "type" : "user"
    }
    user0003 = {
        "firstName" : "Jerry",
        "lastName" : "Wasaracecardriver",
        "email" : "jerry.wasaracecardriver@acme.com(opens in new tab)",
        "tagLine" : "el sob number one",
        "type" : "user"
    }

    Documents are created using the bucket.insert() and bucket.insert_multi() methods. They can also be created using the bucket.upsert() and bucket.upsert_multi() methods.

    The code to store a single user in the default bucket would look like the following:

    #insert a single document
    rv = bucket.upsert('newDoc1', user0001)
    print (rv)
    • The user0001 is defined as a series of JSON key-value pairs.

    • The newDoc1 is the name of the document you want to create.

    The code to store multiple users in the default bucket would look like the following:

    rv = bucket.upsert_multi({'newDoc2':user0002, 'newDoc3':user0003})
    print (rv)
    Since SDK 3.0 all Key-Value operations are executed on the collection level instead of the bucket level.

    To recover the document by the id, you can use the bucket.get() method.

    # first lookup using the key
    rv = bucket.get('newDoc2')
    print(rv.value)

    Finally, here is how you query the database when you need all users where the email ends with @acme.com:

    #first secondary lookup to find all users with email ending in @acme.com
    
    query_result = cluster.query('SELECT * FROM `default` WHERE email LIKE $email', QueryOptions(named_parameters={'email': "%@acme.com"}))
    for row in query_result:
       print(row)

    Here is all of the code for our class:

    # these modules are used to access and authenticate with your database cluster:
    from couchbase.cluster import Cluster, ClusterOptions, QueryOptions
    from couchbase_core.cluster import PasswordAuthenticator
    
    # specify the cluster and specify an authenticator containing a username and password to be passed to the cluster.
    
    cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('Administrator', 'password')))
    
    # following a successful authentication, a bucket can be opened.
    # access a bucket in that cluster
    
    bucket = cluster.bucket('default')
    coll = bucket.default_collection()
    
    # following a successful authentication, a bucket can be accessed to perform operations
    
    # JSON Object for user0001
    user0001 = {
        "firstName" : "Perry",
        "lastName" : "Mason",
        "email" : "perry.mason@acme.com",
        "tagLine" : "Who can we get on the case?",
        "type" : "user"
    }
    
    #insert a single document
    rv = bucket.upsert('newDoc1', user0001)
    print (rv)
    
    #insert multiple documents
    
    user0002 = {
        "firstName" : "Major",
        "lastName" : "Tom",
        "email" : "major.tom@acme.com(opens in new tab)",
        "tagLine" : "Send me up a drink",
        "type" : "user"
    }
    user0003 = {
        "firstName" : "Jerry",
        "lastName" : "Wasaracecardriver",
        "email" : "jerry.wasaracecardriver@acme.com(opens in new tab)",
        "tagLine" : "el sob number one",
        "type" : "user"
    }
    
    rv = bucket.upsert_multi({'newDoc2':user0002, 'newDoc3':user0003})
    print (rv)
    
    # first lookup using the key
    rv = bucket.get('newDoc2')
    print(rv.value)
    
    #first secondary lookup to find all users with email ending in @acme.com
    
    query_result = cluster.query('SELECT * FROM `default` WHERE email LIKE $email', QueryOptions(named_parameters={'email': "%@acme.com"}))
    for row in query_result:
       print(row)
    Make sure you have at least a primary index in your bucket before running the code.

    If you want to run the code to see its output, copy the complete code into a file, say connect.py, and run python3 connect.py.