How to Use Port-Based Database Selection in Django (With SQL Server + Multiple Databases) || DN-SPACE

Python Django

How to Use Port-Based Database Selection in Django (With SQL Server + Multiple Databases)

When working with large organizations or multi-branch systems, it's common to maintain multiple databases that store similar structured data. Instead of running separate Django projects for each database, we can run a single Django application and switch the database based on the port used in the request.

This guide explains how to configure port-wise database routing in Django using SQL Server and the mssql-django backend.

Why Use Port-Based Database Selection?

Scenario	Benefit
Multi-branch system (Branch A, Branch B, etc.)	Each branch works on its own database
Shared application logic	One codebase, many databases
Easy deployment & maintenance	Update once → effects all branches
Simple request routing	Port decides which DB is active

Example:

Port	Selected Database	Example URL
`8001`	`DB_MAIN_2024`	`http://server:8001/`
`8002`	`DB_BRANCH_2025`	`http://server:8002/`

How It Works (High-Level Flow)

Incoming Request
       ↓
Middleware reads the port number
       ↓
db_selector stores selected DB in thread-local memory
       ↓
db_router decides which DB to use for ORM operations
       ↓
SQL Server executes the query

This ensures each request uses only the database belonging to its port.

1. settings.py Configuration

DATABASES = {
    # Leave default empty (we are not using it)
    "default": {},

    "DB_MAIN_2024": {
        "ENGINE": "mssql",
        "NAME": "DB_MAIN_2024",
        "HOST": "",
        "USER": "",
        "PASSWORD": "",
        "PORT": "1433",
        "OPTIONS": {"driver": "ODBC Driver 17 for SQL Server"},
    },

    "DB_BRANCH_2025": {
        "ENGINE": "mssql",
        "NAME": "DB_BRANCH_2025",
        "HOST": "",
        "USER": "",
        "PASSWORD": "",
        "PORT": "1433",
        "OPTIONS": {"driver": "ODBC Driver 17 for SQL Server"},
    },
}

DATABASE_ROUTERS = ["config.db_router.DatabaseRouter"]

MIDDLEWARE.insert(0, "config.middleware.PortDatabaseMiddleware")

2. config/db_selector.py

import threading

_local = threading.local()

def set_db(alias):
    _local.DB_ALIAS = alias

def get_db():
    return getattr(_local, "DB_ALIAS", None)

3. config/middleware.py

from django.utils.deprecation import MiddlewareMixin
from .db_selector import set_db

PORT_DB_MAP = {
    8001: "DB_MAIN_2024",
    8002: "DB_BRANCH_2025",
}

class PortDatabaseMiddleware(MiddlewareMixin):
    def process_request(self, request):
        port = request.get_port()
        port = int(port) if port.isdigit() else None

        db_alias = PORT_DB_MAP.get(port)
        if db_alias:
            set_db(db_alias)

4. config/db_router.py

from .db_selector import get_db

class DatabaseRouter:
    def db_for_read(self, model, **hints):
        return get_db()

    def db_for_write(self, model, **hints):
        return get_db()

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return False

How to Add a New Database + New Port

Suppose you need a 3rd database DB_CITY_2026 on port 8003.

Step 1: Add DB to `settings.py`

"DB_CITY_2026": {
    "ENGINE": "mssql",
    "NAME": "DB_CITY_2026",
    "HOST": "",
    "USER": "",
    "PASSWORD": "",
    "PORT": "1433",
    "OPTIONS": {"driver": "ODBC Driver 17 for SQL Server"},
},

Step 2: Add mapping to `middleware.py`

Step 3: Restart Application

Done.

Pre-Deployment Checklist

✅ Item	Why
Database exists	Must be created first
Login credentials correct	Avoid auth failure
SQL Server port 1433 open	Networking requirement
ODBC Driver installed	Required backend driver
DB entry added in settings.py	For Django to see it
Port mapping added in middleware	For routing to work
App restarted	Config must reload

Conclusion

This architecture allows:

One Django codebase
Multiple databases
Clean port-based switching
Easy scaling for future branches/clients/cities

subscribe to our newsletter

Get the latest news and updates by signing up to our daily newsletter.We won't sell your email or spam you !

Python Django