Migrate Django apps from other databases to SQL Server

This article provides guidance for migrating Django applications from PostgreSQL, MySQL, or SQLite to SQL Server using the mssql-django backend.

Overview

Django's ORM abstracts most database differences, but some behaviors and SQL dialects vary between backends. This guide covers the key differences you encounter when migrating to SQL Server.

Step 1: Install mssql-django

Install the mssql-django package and its dependencies:

pip install mssql-django

Ensure the Microsoft ODBC Driver for SQL Server is installed. See Install mssql-django for platform-specific instructions.

Step 2: Update DATABASE configuration

Replace your existing database configuration in settings.py:

# Example: From PostgreSQL
# DATABASES = {
#     "default": {
#         "ENGINE": "django.db.backends.postgresql",
#         "NAME": "mydb",
#     },
# }

# To SQL Server
DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Step 3: Create fresh migrations

Start with a clean migration history for SQL Server:

# Remove existing migration files (keep __init__.py)
# Then regenerate
python manage.py makemigrations
python manage.py migrate

Key differences from PostgreSQL

PostgreSQL-specific features to replace

If your code uses PostgreSQL-specific features from django.contrib.postgres, replace them:

# PostgreSQL ArrayField - replace with JSONField or related table
# Before
from django.contrib.postgres.fields import ArrayField
tags = ArrayField(models.CharField(max_length=50))

# After (using JSONField)
tags = models.JSONField(default=list)

# PostgreSQL HStoreField - replace with JSONField
# Before
from django.contrib.postgres.fields import HStoreField
metadata = HStoreField()

# After
metadata = models.JSONField(default=dict)

Key differences from MySQL

Key differences from SQLite

Collation differences

Collation controls how SQL Server compares and sorts text. This is one of the most common sources of unexpected behavior when migrating from PostgreSQL or MySQL.

Case sensitivity

SQL Server's default collation (SQL_Latin1_General_CP1_CI_AS) is case-insensitive. PostgreSQL is case-sensitive by default.

This behavior means that after migration, queries that previously distinguished between "Smith" and "smith" treat them as equal:

# On PostgreSQL: returns only exact case matches
# On SQL Server (default collation): returns both "Smith" and "smith"
User.objects.filter(last_name="Smith")

If your application depends on case-sensitive comparisons, you have two options:

• Change the database or column collation to a case-sensitive variant:

  -- Database-level (affects all new columns)
  ALTER DATABASE [<your-database>] COLLATE Latin1_General_CS_AS;
  
  -- Column-level (for specific columns)
  ALTER TABLE [<your-table>]
  ALTER COLUMN [<column-name>] NVARCHAR (150) COLLATE Latin1_General_CS_AS;
  

• Use Django's __exact lookup with a collation override in raw SQL for targeted queries.

Accent sensitivity

The default SQL Server collation is accent-sensitive (AS), which matches PostgreSQL's behavior. Characters like é and e are treated as different. If you need accent-insensitive comparisons, use a collation ending in _AI.

Configure collation in mssql-django

Override the default collation for text field lookups in your database configuration:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "collation": "Latin1_General_CS_AS",  # Case-sensitive
        },
    },
}

Step 4: Update custom SQL

If your code contains raw SQL, update it for SQL Server syntax:

# PostgreSQL syntax
# cursor.execute("SELECT * FROM products LIMIT 10 OFFSET 20")

# SQL Server syntax
cursor.execute("SELECT * FROM products ORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY")

Common SQL syntax differences:

Transaction isolation differences

PostgreSQL uses MVCC (Multi-Version Concurrency Control) for its READ COMMITTED isolation level. Readers never block writers and writers never block readers.

SQL Server's default READ COMMITTED uses locking, which means read queries can block while waiting for write transactions to complete. If your application experiences increased blocking after migration, consider enabling READ COMMITTED SNAPSHOT on the database:

ALTER DATABASE [<your-database>]
SET READ_COMMITTED_SNAPSHOT ON;

This changes SQL Server's READ COMMITTED to use row versioning (similar to PostgreSQL's MVCC) instead of locking. Readers see the last committed version of a row without waiting for active writers.

Step 5: Migrate data

Data migration strategy depends on dataset size:

Small datasets (<500 MB)

Use Django's dumpdata/loaddata:

# On the source database
python manage.py dumpdata --natural-foreign --natural-primary -o data.json

# Switch settings.py to SQL Server, then:
python manage.py migrate
python manage.py loaddata data.json

Large datasets (>500 MB)

For large migrations, use specialized tools to avoid memory exhaustion and timeout issues. Django's ORM isn't the right tool for bulk loads at this scale. Bypass it for the data move and let Django manage schema and application logic afterward.

Post-migration validation

After migration, validate identity seed consistency for auto-increment columns:

-- Check identity seed and current value for all tables
SELECT 
    TABLE_NAME,
    IDENT_SEED(TABLE_SCHEMA + '.' + TABLE_NAME) AS IdentitySeed,
    IDENT_INCR(TABLE_SCHEMA + '.' + TABLE_NAME) AS IdentityIncrement,
    IDENT_CURRENT(TABLE_SCHEMA + '.' + TABLE_NAME) AS CurrentIdentity
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_TYPE = 'BASE TABLE'
    AND OBJECTPROPERTY(OBJECT_ID(TABLE_SCHEMA + '.' + TABLE_NAME), 'TableHasIdentity') = 1
ORDER BY TABLE_NAME;

If CurrentIdentity exceeds IdentitySeed + record_count, reseed:

DBCC CHECKIDENT ('your_table', RESEED, new_seed);

Related content

• Migrate Django apps from PostgreSQL to SQL Server
• Install mssql-django
• Django field to SQL Server type mappings
• Limitations and unsupported features in mssql-django
• Transaction management in mssql-django
• Time zone support in mssql-django
• JSONField with SQL Server