During new feature development, we frequently introduce new API versions to roll out new features gradually while keeping the existing API functional for the connected client applications. Oftentimes, the new API version has a new database schema change and we need to serve different datasets based on the API version. In such scenarios, we can use Neon’s branching feature to dynamically manage database versions instead of creating separate databases or handling costly data migrations. This allows us to keep multiple versions of an API with different data structures.

In this guide, we will:

1. Use Neon’s API to create and manage database branches dynamically.
2. Implement a FastAPI backend service that automatically connects to different database branches.

You can also try out the example on the GitHub repository.

Use Case: Versioned APIs with Dynamic Databases

Let’s say we have an API that manages user data. The v1 API only has id, name, and email, in the User table while the v2 API introduces additional fields like age and city. We use Neon database branching to create different database versions dynamically. We can keep each API version isolated without modifying production data.

This means that:

• API v1 can connect to one branch of the database.
• API v2 can connect to another branch with an updated schema.

Version	Columns
v1	id, name, email
v2	id, name, email, age, city

Lets try to implement this simple project.

Step-by-Step API Versioning Implementation

Prerequisites

Before we begin, make sure you have the following:

• Python 3.8 or later version
• A free Neon account

Create a Neon Project

1. Navigate to the Neon Console
2. Click “New Project”
3. Select Azure as your cloud provider
4. Choose East US 2 as your region
5. Give your project a name (e.g., “api-versioning-neondb”)
6. Click “Create Project”
7. Once the project is created successfully, copy the Project ID from Settings under the project settings view.
8. Retrieve the Neon API Key: Create a new API Key, copy it, and save it safely. We will use it in the project.

Set Up FastAPI Project in Python

Project Structure

The final project structure looks like this:

Set Up Environment Variables

Create a .env file in the project root directory:

Add Python Dependencies

Lists Python dependencies in requirements.txt file:

uvicorn==0.34.0
fastapi==0.115.8
requests==2.32.3
psycopg2-binary==2.9.10
python-dotenv==1.0.1

Initialize Database Schema

Define Schema for API v1:

Install virtual environment (Preferred)

python3 -m venv env
source env/bin/activate

Install the required dependencies

pip install -r requirements.txt

Managing Neon Database Branches

We need to create a new branch for each API version. This is done using Neon’s API programmatically.

The below neon_db_setup.py script does the following things:

• Checks if a branch already exists. Creates a new branch for the API version if it doesn’t.
• Fetches connection strings for new branches.
• Initializes schema automatically per branch and populates branch databases with sample data by running SQL queries we specified in the data folder.

Everything happens at project startup time and Neon creates new branches instantly.

Connecting API Version to the Correct Database Branch

We also need to retrieve the correct CONNECTION_STRINGS for database branches. To do so, we can add a helper db_connection.py Python script that returns the connection string based on the given API version:

Create FastAPI Service

Finally, we create two API routes for V1 and V2 versions. Each API version fetches different columns based on its database schema.

Test Created Branches

You can easily verify branches created for API versions in the Neon Console:

Running the API locally

Start the API server:

uvicorn app.main:app --reload

Test the endpoints

Fetch users from v1 (old version)

curl -X GET "<http://localhost:8000/v1/users>"

Response:

[
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
]

Fetch users from v2 (new version with extra fields)

curl -X GET "<http://localhost:8000/v2/users>"

Response:

[
    {"id": 1, "name": "Alice", "email": "alice@example.com", "age": 25, "city": "New York"},
    {"id": 2, "name": "Bob", "email": "bob@example.com", "age": 30, "city": "San Francisco"}
]

Well done! Everything is working as its expected.

Next Steps

• You can use Neon’s Schema Diff feature to track and compare schema changes between branches. The Schema Diff tool allows you to easily identify differences between the schemas of two Neon branches. This can be achieved via Neon Console or API endpoint.

• When the old API deprecates, you can make the V2 branch as a default and remove the old V1 branch safely.

Conclusion

In this project, we demonstrated how to dynamically manage API versions and database schemas using Neon database branching in FastAPI. In the next articles, we will learn how to deploy the FastAPI service to Azure Cloud and use Azure API Management to route requests to the correct API version. Try out the GitHub repository example!

---

Neon is a serverless Postgres platform that helps teams ship faster via instant provisioning, autoscaling, and database branching. We have a Free Plan – you can get started without a credit card.