FastAPI Search Cookiecutter

This cookiecutter builds a lean microservice that interacts with an RDBMS, currently only PostgreSQL, and a search database, currently either OpenSearch or ElasticSearch.

Status

The fastapi-search-cookiecutter repo is early stage, with rough edges and essential functionality at a “wip” stage.

Vision

The vision and motivation for this service template is simplicity and performance. What inspired the work is the lack of a clean and simple service stack that uses SQL directly, sans ORM compiled queries, and a DSL for managing the search database.

The presumption is that an RDBMS is the source of data truth. The primary database typically involves a complex, interrelated schema that routinely calls for hand tuned query optimization. The search database will house non-normalized data from the primary database and provides the power of reverse index queries, multiple index mappings per field, faceting, etc. The flat document architecture of the search DB is amenable to service language level DSL, such as elasticsearch-dsl and opensearch-dsl.

A Word Regarding ElasticSearch v OpenSearch

Nuetrality.

Getting started

Prerequisites

• Pyenv
• Python 3.10 (via in pyenv)
• Poetry
• Cookiecutter

Usage

• Run cookiecutter on this repo (or clone it and cite it locally.)

cookiecutter https://github.com/fapi-search/fastapi-search-cookiecutter.git

• Answer the cookiecutter questions or accept defaults, e.g.,

project_name [Search Project]: 
project_slug [search-project]: 
default_local_host [0.0.0.0]: 
default_local_port [8001]: 
default_docker_port [8000]: 
Select search_backend:
1 - elasticsearch
2 - opensearch
Choose from 1, 2 [1]: 
default_postgres_url [postgresql+asyncpg://db_user:db_pass@localhost:5432/app_db]: 
default_search_url [http://elastic:elastic@localhost:9200]: 
use_precommit [y]: 

• After building the project tree, this cookie cutter will do the following post-processing (outputs ommited)…
  • *** git init && git add . && git commit *** Initialize a git repo and commit copied files
  • *** poetry install *** Install with poetry into virtualenv from pyproject.toml.
  • *** git add poetry.lock && git commit -m 'Add poetry.lock' *** Add the poetry.lock file to the repo. (We keep the lock file out of the cookiecutter intentionally.)
  • *** poetry run pre-commit install *** Install the pre-commit tools from .pre-commit-config.yaml (if pre-commit is selected). See pre-commit for more information.
  • *** poetry run pre-commit run --all-files *** Run pre-commit in the project. This cleans up formatting and linting issues that may occur in the application of the cookiecutter template.
  • *** git commit -a -m 'pre-commit cleanup' *** If the previous step changed anything, commit those changes.
• Try it out

cd search-project
poetry install
poetry run ./run.sh

And visit http://localhost:8001/docs. Note that if you don’t have a Postgres database created and migrated, and an Elastic/Open Search service running, API endpoints will fail. A docker-compose.yml is provided in the cookie’d project. See the README.md in your new project for instructions.

Contributing

See the contributing doc.

Acknowledgements

• ChristopherGS’s fine FastAPI tutorial (one of the best out there), especially borrowed snippets from his part-08-structure-and-versioning repo files.
• The aforementioned doc draws heavily on the Full Stack FastAPI PostgreSQL template and of course FastAPI itself.
• The Starlette Project and anything Encode touches, bedrock of first class Python tech.
• Dockerfile borrowed from https://github.com/svx/poetry-fastapi-docker which is forked from https://github.com/michaeloliverx/python-poetry-docker-example