> Full Neon documentation index: https://neon.com/docs/llms.txt # Building a high-performance API with FastAPI, Pydantic, and Lakebase Postgres Learn how to create an API for managing a tech conference system using FastAPI, Pydantic for data validation, and Lakebase Postgres on Neon for data storage FastAPI is a high-performance Python web framework for building APIs. Combined with Pydantic for data validation and Lakebase Postgres on Neon for data storage, you can build an API with little code. In this guide, we'll build an API for managing a tech conference system, with a focus on best practices and performance. ## Prerequisites Before we begin, make sure you have the following: - Python 3.9 or later installed on your system - [pip](https://pip.pypa.io/en/stable/installation/) for managing Python packages - A [Neon](https://console.neon.tech/signup) account ## Setting up the project Let's start by creating a new project directory and setting up a virtual environment: 1. Create a new directory and navigate to it: ```bash mkdir fastapi-neon-conference-api cd fastapi-neon-conference-api ``` 2. Create a virtual environment: ```bash python -m venv venv ``` Creating a virtual environment isolates your project dependencies from other Python installations on your system. 3. Activate the virtual environment: - On Windows: ```bash venv\Scripts\activate ``` - On macOS and Linux: ```bash source venv/bin/activate ``` You should see `(venv)` in your terminal prompt, indicating that the virtual environment is active. Now, let's install the necessary packages for our project using `pip`: ```bash pip install fastapi uvicorn sqlalchemy psycopg2-binary "pydantic[email]" python-dotenv ``` This command installs: - FastAPI: Our web framework - Uvicorn: An ASGI server to run our FastAPI application - SQLAlchemy: An ORM for database interactions - psycopg2-binary: Postgres adapter for Python - Pydantic: For data validation and settings management - python-dotenv: To load environment variables from a .env file With the dependencies installed, we can start building our API. You can also create a `requirements.txt` file to manage your dependencies by running: ```bash pip freeze > requirements.txt ``` This will create a `requirements.txt` file with all the installed packages in your virtual environment and their versions. This is useful for sharing your project with others or deploying it to a server. ## Connecting to your database on Neon First, let's set up our database connection. Create a `.env` file in your project root: ```env DATABASE_URL=postgres://user:password@your-neon-hostname.neon.tech/neondb?sslmode=require&channel_binding=require ``` Replace the placeholders with your Neon connection string, which you can copy by clicking **Connect** on your project dashboard in the Neon Console. Now, create a `database.py` file to manage the database connection: ```python from sqlalchemy import create_engine from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker from dotenv import load_dotenv import os load_dotenv() SQLALCHEMY_DATABASE_URL = os.getenv("DATABASE_URL") engine = create_engine(SQLALCHEMY_DATABASE_URL) SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) Base = declarative_base() def get_db(): db = SessionLocal() try: yield db finally: db.close() ``` This script does the following: 1. Loads the environment variables from `.env` using `load_dotenv` 2. Creates a SQLAlchemy engine using the database URL from the environment variables 3. Creates a SessionLocal class for database sessions 4. Defines a Base class for declarative models which will be used to create database tables 5. Provides a `get_db` function to manage database connections We're now ready to define our database models and API endpoints. ## Defining models and schemas Let's start by creating an API for managing a tech conference system. We'll need database models and Pydantic schemas for talks and speakers. Create a `models.py` file for SQLAlchemy models and relationships: ```python from sqlalchemy import Column, Integer, String, ForeignKey, DateTime from sqlalchemy.orm import relationship from database import Base class Speaker(Base): __tablename__ = "speakers" id = Column(Integer, primary_key=True, index=True) name = Column(String, index=True) bio = Column(String) company = Column(String) talks = relationship("Talk", back_populates="speaker") class Talk(Base): __tablename__ = "talks" id = Column(Integer, primary_key=True, index=True) title = Column(String, index=True) description = Column(String) speaker_id = Column(Integer, ForeignKey("speakers.id")) start_time = Column(DateTime) end_time = Column(DateTime) speaker = relationship("Speaker", back_populates="talks") ``` This defines `Speaker` and `Talk` models with their respective fields and relationships. The `speaker_id` field in the `Talk` model establishes a foreign key relationship with the `Speaker` model using SQLAlchemy's `ForeignKey` construct. Now, create a `schemas.py` file for Pydantic models with data validation: ```python from pydantic import BaseModel from datetime import datetime from typing import List, Optional class TalkBase(BaseModel): title: str description: str start_time: datetime end_time: datetime class TalkCreate(TalkBase): speaker_id: int class Talk(TalkBase): id: int speaker_id: int class Config: orm_mode = True class SpeakerBase(BaseModel): name: str bio: str company: str class SpeakerCreate(SpeakerBase): pass class Speaker(SpeakerBase): id: int talks: List[Talk] = [] class Config: orm_mode = True class SpeakerWithTalks(Speaker): talks: List[Talk] ``` Here we define Pydantic models for creating and returning speaker and talk data. The `TalkCreate` model includes a `speaker_id` field for associating talks with speakers. The `SpeakerWithTalks` model extends the `Speaker` model to include a list of talks. The `orm_mode = True` configuration lets Pydantic read data directly from SQLAlchemy models. In Pydantic v2, this setting is named `from_attributes = True`. Our API endpoints use these models to validate incoming data and serialize outgoing data, so you don't have to convert data by hand. ## Creating API endpoints Now, let's create our FastAPI application with CRUD operations for speakers and talks. Create a `main.py` file: ```python from fastapi import FastAPI, Depends, HTTPException from sqlalchemy.orm import Session from typing import List import models, schemas from database import engine, get_db models.Base.metadata.create_all(bind=engine) app = FastAPI() @app.post("/speakers/", response_model=schemas.Speaker) def create_speaker(speaker: schemas.SpeakerCreate, db: Session = Depends(get_db)): db_speaker = models.Speaker(**speaker.dict()) db.add(db_speaker) db.commit() db.refresh(db_speaker) return db_speaker @app.get("/speakers/", response_model=List[schemas.Speaker]) def read_speakers(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)): speakers = db.query(models.Speaker).offset(skip).limit(limit).all() return speakers @app.get("/speakers/{speaker_id}", response_model=schemas.SpeakerWithTalks) def read_speaker(speaker_id: int, db: Session = Depends(get_db)): db_speaker = db.query(models.Speaker).filter(models.Speaker.id == speaker_id).first() if db_speaker is None: raise HTTPException(status_code=404, detail="Speaker not found") return db_speaker @app.post("/talks/", response_model=schemas.Talk) def create_talk(talk: schemas.TalkCreate, db: Session = Depends(get_db)): db_talk = models.Talk(**talk.dict()) db.add(db_talk) db.commit() db.refresh(db_talk) return db_talk @app.get("/talks/", response_model=List[schemas.Talk]) def read_talks(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)): talks = db.query(models.Talk).offset(skip).limit(limit).all() return talks @app.get("/talks/{talk_id}", response_model=schemas.Talk) def read_talk(talk_id: int, db: Session = Depends(get_db)): db_talk = db.query(models.Talk).filter(models.Talk.id == talk_id).first() if db_talk is None: raise HTTPException(status_code=404, detail="Talk not found") return db_talk ``` This code defines endpoints for: - Creating and retrieving speakers at `/speakers/` - Retrieving a specific speaker with their talks at `/speakers/{speaker_id}` - Creating and retrieving talks at `/talks/` - Retrieving a specific talk at `/talks/{talk_id}` Each endpoint uses dependency injection to get a database session, which is closed when the request finishes. Pagination is supported for the `read_speakers` and `read_talks` endpoints using the `skip` and `limit` parameters to avoid loading large datasets at once. ## Running the API To run the API, use the following command: ```bash python -m uvicorn main:app --reload ``` This starts the Uvicorn server with hot-reloading enabled for development. By default, the API will be available on port 8000. You can access the API documentation at `http://127.0.0.1:8000/docs` or `http://127.0.0.1:8000/redoc`. Your database tables will be created automatically when you run the API for the first time thanks to the `models.Base.metadata.create_all(bind=engine)` line in `main.py`. You can see the tables in the **Tables** page of the Neon Console. ## Testing the API You can test the API using tools like `curl`, `Postman`, or the `/docs` endpoint that FastAPI serves in your browser. Let's test this out using `httpie`, a command-line HTTP client: 1. Start by creating a speaker: ```bash http POST http://127.0.0.1:8000/speakers/ name="John Doe" bio="Software Engineer" company="Tech Inc." ``` You should see a response with the created speaker data. 2. Next, create a talk associated with the speaker: ```bash http POST http://127.0.0.1:8000/talks/ title="Introduction to FastAPI" description="Learn how to build APIs with FastAPI" start_time="2024-08-18T09:00:00" end_time="2024-08-18T10:00:00" speaker_id=1 ``` This will create a talk associated with the speaker created earlier and return the talk data. 3. Retrieve all speakers: ```bash http http://127.0.0.1:8000/speakers/ ``` This endpoint will return a list of all speakers in the database. 4. Retrieve a specific speaker with talks: ```bash http http://127.0.0.1:8000/speakers/1 ``` This will return the speaker data along with any talks associated with them. 5. Retrieve all talks: ```bash http http://127.0.0.1:8000/talks/ ``` 6. Retrieve a specific talk: ```bash http http://127.0.0.1:8000/talks/1 ``` You can modify these requests to test other endpoints and functionalities. ## Dockerizing the application To deploy your FastAPI application, you may want to containerize it. Here's how you can create a Dockerfile for your project: ```Dockerfile FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] ``` This Dockerfile uses a slim Python image, installs dependencies from a `requirements.txt` file, copies the project files, and runs the Uvicorn server. To build a new Docker image, run the following command in your project directory: ```bash docker build -t fastapi-neon-conference-api . ``` You can then run the Docker container with: ```bash docker run -d -p 8000:8000 fastapi-neon-conference-api ``` This will start the FastAPI application in a Docker container, accessible on port 8000 of your host machine. Make sure your `.env` file isn't included in the Docker image. Instead, you can pass the environment variables as arguments when running the container. ## Performance considerations 1. **Database indexing**: We've added indexes to frequently queried fields (`id`, `name`, `title`) in our models. This improves query performance. To learn more about indexing, see [Postgres index types](https://neon.com/docs/postgresql/index-types). 2. **Pagination**: The `read_speakers` and `read_talks` endpoints include `skip` and `limit` parameters for pagination, preventing the retrieval of unnecessarily large datasets. 3. **Dependency injection**: With `Depends(get_db)`, each request's database session is closed after the request. This prevents connection leaks. 4. **Pydantic models**: Using Pydantic for request and response models provides automatic data validation and serialization, reducing the need for manual checks. 5. **Relationships**: We've used SQLAlchemy relationships to load related data (speakers and their talks). By default, SQLAlchemy loads a relationship lazily with a separate query; use `joinedload` or `selectinload` if you need to avoid extra queries. ## Conclusion You've built a simple API for managing a tech conference system using FastAPI, Pydantic, and Lakebase Postgres on Neon. As a next step, you can extend the API with more features like authentication, authorization, and advanced query capabilities. You can check out the [Implementing secure user authentication in FastAPI using JWT tokens and Lakebase Postgres](https://neon.com/guides/fastapi-jwt) guide for adding JWT-based authentication to your API. ## Additional resources - [FastAPI Documentation](https://fastapi.tiangolo.com/) - [Pydantic Documentation](https://docs.pydantic.dev/latest/) - [SQLAlchemy Documentation](https://docs.sqlalchemy.org/) - [Neon Documentation](https://neon.com/docs) --- Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/guides/fastapi-overview"}` to https://feedback.neon.tech/ (no auth required).