{"id":12959,"date":"2022-03-29T08:00:05","date_gmt":"2022-03-29T15:00:05","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=12959"},"modified":"2025-06-13T21:25:02","modified_gmt":"2025-06-14T04:25:02","slug":"build-a-python-microservice-with-couchbase-part-1","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/build-a-python-microservice-with-couchbase-part-1\/","title":{"rendered":"Build A Python Microservice With Couchbase – Part 1"},"content":{"rendered":"

Microservices require a scalable and sustainable set of components. This post introduces how to build microservices using Python and Couchbase to provide a fully-scalable solution.<\/span><\/p>\n

Monolithic applications present many challenges. They were born in an age when everything ran on one system, usually a mainframe or minicomputer. <\/span>Service-Oriented Architecture<\/span><\/a> unleashed applications, allowing them to use scale-out shared-nothing collections of commodity servers. It allowed parts of an application landscape to be discretely scaled as needed. Today, we have similar patterns, except the servers have been replaced with virtual machines or cloud instances.\u00a0<\/span><\/p>\n

Some Service-Oriented Architectures are collections of small to large applications that need to interoperate. This allows for some disaggregation and horizontal scaling but does not solve all the challenges of achieving global cloud scalability because each service is often a monolithic application. Large applications are not only difficult to scale but also a challenge to develop. They require a lot of coding and maintenance. Simple code updates can require complete regression testing, which needs considerable effort.\u00a0<\/span><\/p>\n

Enter the <\/span>Microservices Architecture<\/span><\/a>. This architectural pattern splits each application component into small pieces that can be independently scaled. They are usually stateless so that they can be spun up and shut down as needed. The main challenge becomes network latency, but this usually isn’t a problem since high-speed networks are ubiquitous today.<\/span><\/p>\n

Microservice design<\/span><\/h2>\n

A good microservice should be lightweight and stateless. The goal of a Microservices Architecture<\/a> is to break application functionality into discrete, independently operating components. Each microservice should serve one functional area of the overall application. What is most important is that each microservice should be able to evolve independently from the rest of the application landscape. This works well with an <\/span>Agile development methodology<\/span><\/a>, enabling teams to rapidly deliver new functionality without impacting the overall application.<\/span><\/p>\n

It has been said that microservices should be designed for failure. This might sound odd at first, but it makes perfect sense if you consider the nature and lifecycle of a microservice. A good microservice should be ephemeral. Since they are stateless, you should be able to add and remove microservice instances without impacting the application.<\/span><\/p>\n

Since the microservices will be in perpetual flux, all interaction with them should be via an API style that works well in this environment. As such, <\/span>RESTful interfaces<\/span><\/a> are a good choice for the API design. REST calls are ephemeral, and they function well behind a network load-balancer (which is one method to make REST-based microservices highly available and scalable).<\/span><\/p>\n

Finally, they should be easy to deploy and automate with popular DevOps tools. Each service should be able to run either on a system with other services or in a container. Kubernetes, a container orchestration technology, was essentially created for microservices.<\/span><\/p>\n

Building a user profile microservice<\/span><\/h2>\n

It is difficult to make an entire application out of microservices. Core business logic often needs to be provided by some application that just can\u2019t be rewritten with microservices. For example, you may need to interact with an off-the-shelf ERP or CRM application stack. But for Web and Mobile applications, it is a common pattern to front-end such large systems with microservices to control the end-user experience.<\/span><\/p>\n

Technology consumers want a fast and personalized experience when they interact with a web or mobile application. With microservices, you can globally distribute the most frequently used elements of the presentation layer to be geographically close to the end-user. You can also independently scale these components based on usage patterns.<\/span><\/p>\n

One frequent component of a web or mobile application is the concept of user profiles. This is usually the \u201csilhouette of a person\u201d icon in the upper righthand portion of a user interface. User profiles can be either simplistic with basic demographic information or highly detailed with rich information about preferences and history to drive personalized changes to a user\u2019s experience.<\/span><\/p>\n

This series of blog posts discusses using Python to provide a RESTful interface to user profile data hosted in a Couchbase database. We will use a simple example with a basic schema for illustrative purposes. However, you can enhance this example as much as needed for a \u201creal world\u201d application.<\/span><\/p>\n

Why use Couchbase for microservices?<\/span><\/h2>\n

Couchbase combines multiple data processing elements into a unified data platform. Couchbase includes a key-value engine, support for relational schemas, a full SQL query engine, a complete text search engine, an eventing engine and an analytics engine. It provides microsecond response times and eliminates the need for organizations to choose different systems for different workloads.<\/span><\/p>\n

A user profile service is typically a frequently accessed service. At a minimum, along with authorization and authentication, it is accessed every time a user logs into an application. However, the more likely scenario is it will need to be accessed many times while someone interacts with an application. As such, performance and latency will be essential characteristics of the design.\u00a0<\/span><\/p>\n

The memory-first architecture of Couchbase allows it to deliver blazingly fast performance. Couchbase performance is near-linear with its scale-out, shared-nothing architecture that enables it to maintain throughput and latencies as the cluster is scaled. Couchbase can scale in conjunction with the microservice elements because the microservice architecture is also scale-out, shared-nothing.<\/span><\/p>\n

Couchbase is designed to eliminate many traditional administrative tasks. Couchbase leverages a dynamic data containment model with auto-sharding and rebalancing of data, and by separating index management from data management. With the <\/span>Capella Couchbase Cloud offering<\/span><\/a>, or on-prem with tools such as Terraform or Kubernetes and the <\/span>Couchbase Autonomous Operator<\/span><\/a>, database changes and microservice changes can be automated and orchestrated across private and public clouds.<\/span><\/p>\n

Why Python?<\/span><\/h2>\n

This may be the biggest question on your mind as you read this post. Something like Node.js might be the first language that comes to mind. Indeed, per <\/span>Berkeley<\/span><\/a> JavaScript is the most in-demand language, however, Python is the second. Python is very accessible as it is part of the software distribution for Linux and macOS and you can easily install it on Windows. You can have multiple versions of the language installed, and the virtual environment feature makes it easy to have multiple customized environments using different versions of the language. While Python supports multithreading, its threads are not as performant as a language such as Java. Still, Python is lightweight, so it scales nicely with multiprocessing and has packages that make dispatching threads or processes easy. The best part of Python is it is easy to learn and easy to code.<\/span><\/p>\n

Sample application walkthrough<\/span><\/h2>\n

To demonstrate the concept, I created a sample Python Microservice (<\/span>code is on GitHub<\/span><\/a>) that provides a very simple RESTful interface to access user profile information. Couchbase supports JSON, UTF-8 (string), or binary (raw) document types. The JSON format is considered the native format and enables many rich features in the platform, so that is the document format that we will use.<\/span><\/p>\n

Our very simple user profile contains the user\u2019s name and other basic details regarding their account. The profile includes a picture that references a separate record containing the Base64 encoded image file. We could have used the RAW document type, but we put the image into a JSON value for this example.\u00a0<\/span><\/p>\n

We also leverage the scopes and collections feature that was introduced with Couchbase Server 7. User profile documents are stored in the <\/span>user_data <\/span><\/i>collection, and images are stored in the <\/span>user_images <\/span><\/i>collection as illustrated here:<\/span><\/p>\n

\"User<\/a><\/p>\n

User profile document format:<\/span><\/p>\n

{\r\n\u00a0\u00a0\"record_id\": \"1\",\r\n\u00a0\u00a0\"name\": \"Jessica Lopez\",\r\n\u00a0\u00a0\"nickname\": \"jlopez\",\r\n\u00a0\u00a0\"picture\": \"1\",\r\n\u00a0\u00a0\"user_id\": \"jessicalopez9483\",\r\n\u00a0\u00a0\"email\": \"jessica.lopez@example.com\",\r\n\u00a0\u00a0\"email_verified\": \"False\",\r\n\u00a0\u00a0\"first_name\": \"Jessica\",\r\n\u00a0\u00a0\"last_name\": \"Lopez\",\r\n\u00a0\u00a0\"address\": \"6699 West Road\",\r\n\u00a0\u00a0\"city\": \"Weirton\",\r\n\u00a0\u00a0\"state\": \"OR\",\r\n\u00a0\u00a0\"zip_code\": \"21243\",\r\n\u00a0\u00a0\"phone\": \"306-402-6984\",\r\n\u00a0\u00a0\"date_of_birth\": \"03\/05\/1961\"\r\n}<\/pre>\n
User picture document format:<\/span><\/p>\n
{\r\n\u00a0\u00a0\"record_id\": \"1\",\r\n\u00a0\u00a0\"type\": \"jpeg\",\r\n\u00a0\u00a0\"image\": \" AAAADGpQICANC\u2026=\"\r\n}<\/pre>\n
The Python microservice has the option of running either in the foreground where output is echoed to the screen (terminal), or the background as a \u201cdaemon\u201d where output is sent to a log file. The code uses the Python object-oriented class feature to do most of the work.<\/span><\/p>\n
The <\/span>dbConnection<\/span><\/em> class is designed to hold pointers to objects related to the Couchbase database connection. This just makes it easy to pass these around to other classes and functions.<\/span><\/p>\n
The <\/span>couchbaseDriver<\/span><\/em> class handles the interaction with the database. The connect<\/em> function initiates a connection to the Couchbase cluster. It creates objects for accessing the bucket, scope, and collections passed to the function. It stores those objects into a <\/span>dbConnection<\/span><\/em> object which is stored in the class. The <\/span>get<\/span><\/em> function does a key-value retrieval of the key passed to the function from the referenced collection leveraging the established connection. The <\/span>query<\/span><\/em> function does a SQL <\/em><\/span>SELECT<\/span><\/em> on the JSON field from the referenced collection searching for a JSON key that is equal to the specified value.<\/span><\/p>\n
The <\/span>restServer<\/span><\/em> class is a handler class designed to be passed to the Python <\/span>http.server<\/span><\/em> module. It implements the RESTful interface. There are <\/span>GET<\/em> <\/span>endpoints to find user profile data based on the nickname, username, or ID. It also has endpoints to get profile pictures, either by retrieving the JSON document or by returning the image itself. This has an advantage over other REST development frameworks that often only support responding to REST endpoints with JSON content.<\/span><\/p>\n
Finally, the <\/span>microService<\/span><\/em> class starts and stops the HTTP server. It is called from <\/span>main<\/span><\/em> which uses the <\/span>couchbaseDriver<\/span><\/em> to connect to the database and start the microservice. The whole microservice is only a few hundred lines of code, and it can be easily deployed anywhere, and attached to any Couchbase cluster.<\/span><\/p>\n
Up next<\/b><\/h3>\n
In the next part of this series, we will talk about generating random test data for the microservice schema and performance testing.<\/span><\/p>\n
Refer to these resources as your research further on these topics:<\/span><\/p>\n