{"id":45157411,"url":"https://github.com/couchbase-examples/python-quickstart","last_synced_at":"2026-02-20T05:02:40.503Z","repository":{"id":37970192,"uuid":"371026704","full_name":"couchbase-examples/python-quickstart","owner":"couchbase-examples","description":"Entry level Couchbase Python Flask tutorial/demo. Steps to build a REST API to manage the travel-sample bucket.","archived":false,"fork":false,"pushed_at":"2025-11-19T10:03:43.000Z","size":1150,"stargazers_count":6,"open_issues_count":0,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-11-19T12:06:11.744Z","etag":null,"topics":["couchbase","flask-api","flask-restful","hacktoberfest","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2021-05-26T12:31:04.000Z","updated_at":"2025-11-19T10:03:41.000Z","dependencies_parsed_at":"2023-11-22T13:46:15.362Z","dependency_job_id":"d3ed90ab-ccb8-459b-8a47-55c9b22c4f31","html_url":"https://github.com/couchbase-examples/python-quickstart","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/python-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fpython-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fpython-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fpython-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fpython-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/python-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fpython-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["couchbase","flask-api","flask-restful","hacktoberfest","python3"],"created_at":"2026-02-20T05:02:37.109Z","updated_at":"2026-02-20T05:02:40.497Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Python","readme":"# Quickstart in Couchbase with Flask and Python\n\n#### REST API using Couchbase Capella in Python using Flask\n\nOften, the first step developers do after creating their database is to create a REST API that can perform Create, Read, Update, and Delete (CRUD) operations for that database. This repo is designed to teach you and give you a starter project (in Python using Flask) to generate such a REST API. After you have installed travel-sample bucket in your database, you can run this application which is a REST API with Swagger documentation so that you can learn:\n\n1. How to create, read, update, and delete documents using [Key Value operations](https://docs.couchbase.com/python-sdk/current/howtos/kv-operations.html) (KV operations). KV operations are unique to couchbase and provide super fast (think microseconds) queries.\n2. How to write simple parametrized [SQL++ queries](https://docs.couchbase.com/python-sdk/current/howtos/n1ql-queries-with-sdk.html) using the built-in travel-sample bucket.\n\nFull documentation for the tutorial can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-flask-python/).\n\nIf you are looking for a quickstart using [FastAPI](https://fastapi.tiangolo.com/), you can find it in this [repo](https://github.com/couchbase-examples/python-quickstart-fastapi).\n\n## Prerequisites\n\nTo run this prebuilt project, you will need:\n\n- [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/python-sdk/current/ref/travel-app-data-model.html) bucket loaded.\n  - To run this tutorial using a self managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).\n- [Python](https://www.python.org/downloads/) 3.9 or higher installed\n  - Ensure that the Python version is [compatible](https://docs.couchbase.com/python-sdk/current/project-docs/compatibility.html#python-version-compat) with the Couchbase SDK.\n- Loading Travel Sample Bucket\n  If travel-sample is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster:\n  - [Load travel-sample bucket in Couchbase Capella](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data)\n\n## App Setup\n\nWe will walk through the different steps required to get the application running.\n\n### Cloning Repo\n\n```shell\ngit clone https://github.com/couchbase-examples/python-quickstart.git\n```\n\n### Install Dependencies\n\nThe dependencies for the application are specified in the `requirements.txt` file in the source folder. Dependencies can be installed through `pip` the default package manager for Python.\n\n\u003e Note: If your Python is not symbolically linked to python3, you need to run all commands using `python3` instead of `python`.\n\n```shell\ncd src\npython -m pip install -r requirements.txt\n```\n\n\u003e Note: Python SDKs older than version 4.1.9 require OpenSSL v1.1. This might not be the default in some newer platforms. In such scenarios, please install the SDK without using the prebuilt wheels\n\n\u003e `python -m pip install couchbase --no-binary couchbase`\n\n\u003e Refer to the [instructions in the SDK](https://github.com/couchbase/couchbase-python-client#alternative-installation-methods) for more info.\n\n### Setup Database Configuration\n\nTo know more about connecting to your Capella cluster, please follow the [instructions](https://docs.couchbase.com/cloud/get-started/connect.html).\n\nSpecifically, you need to do the following:\n\n- Create the [database credentials](https://docs.couchbase.com/cloud/clusters/manage-database-users.html) to access the travel-sample bucket (Read and Write) used in the application.\n- [Allow access](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) to the Cluster from the IP on which the application is running.\n\nAll configuration for communication with the database is read from the environment variables. We have provided a convenience feature in this quickstart to read the environment variables from a local file, `.env` in the source folder.\n\nCreate a copy of `.env.example` file and rename it to .env and add the values for the Couchbase connection.\n\n```shell\nDB_CONN_STR=\u003cconnection_string\u003e\nDB_USERNAME=\u003cuser_with_read_write_permission_to_travel-sample_bucket\u003e\nDB_PASSWORD=\u003cpassword_for_user\u003e\n```\n\n\u003e Note: The connection string expects the `couchbases://` or `couchbase://` part.\n\n## Running The Application\n\n### Directly on Machine\n\nAt this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.\n\n```sh\ncd src\npython app.py\n```\n\n### Using Docker\n\n- Build the Docker image\n\n```sh\ncd src\ndocker build -t couchbase-flask-quickstart .\n```\n\n- Run the Docker image\n\n```sh\ndocker run -it --env-file .env -p 8080:8080 couchbase-flask-quickstart\n```\n\n\u003e Note: The `.env` file has the connection information to connect to your Capella cluster. These will be part of the environment variables in the Docker container.\n\n### Verifying the Application\n\nOnce the application starts, you can see the details of the application on the logs.\n\n![Application Startup](app_startup.png)\n\nThe application will run on port 8080 of your local machine (http://localhost:8080). You will find the interactive Swagger documentation of the API if you go to the URL in your browser. Swagger documentation is used in this demo to showcase the different API end points and how they can be invoked. More details on the Swagger documentation can be found in the [appendix](#swagger-documentation).\n\n![Swagger Documentation](swagger_documentation.png)\n\n## Running Tests\n\nTo run the integration tests, use the following commands:\n\n```sh\ncd src\npython -m pytest\n```\n\n## Appendix\n\n### Data Model\n\nFor this quickstart, we use three collections, `airport`, `airline` and `routes` that contain sample airports, airlines and airline routes respectively. The routes collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections.\n\n![travel sample data model](travel_sample_data_model.png)\n\n### Extending API by Adding New Entity\n\nIf you would like to add another entity to the APIs, these are the steps to follow:\n\n- Create the new entity (collection) in the Couchbase bucket. You can create the collection using the [SDK](https://docs.couchbase.com/sdk-api/couchbase-python-client/couchbase_api/couchbase_management.html#couchbase.management.collections.CollectionManager.create_collection) or via the [Couchbase Server interface](https://docs.couchbase.com/cloud/n1ql/n1ql-language-reference/createcollection.html).\n- Define the routes in a new file in the `api` folder similar to the existing routes like `airport.py`.\n- Add the new routes to the application in `app.py`.\n- Add the tests for the new routes in a new file in the `tests` folder similar to `test_airport.py`.\n\n### Running Self Managed Couchbase Cluster\n\nIf you are running this quickstart with a self managed Couchbase cluster, you need to [load](https://docs.couchbase.com/server/current/manage/manage-settings/install-sample-buckets.html) the travel-sample data bucket in your cluster and generate the credentials for the bucket.\n\nYou need to update the connection string and the credentials in the `.env` file in the source folder.\n\n\u003e Note: Couchbase Server version 7 or higher must be installed and running prior to running the Flask Python app.\n\n### Swagger Documentation\n\nSwagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.\n\nClick on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts.\n\n#### Trying Out the API\n\nYou can try out an API by clicking on the \"Try it out\" button next to the endpoints.\n\n- Parameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request.\n\n- Execution: Once you've inputted all the necessary parameters, you can click the \"Execute\" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body.\n\n#### Models\n\nSwagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fpython-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fpython-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fpython-quickstart/lists"}