SQLAlchemy 2.1 brings built-in support for mssql-python

We’re pleased to share that SQLAlchemy 2.1.0 is now generally available, with built-in support for mssql-python, Microsoft’s Python driver for SQL Server. You can now use it with SQLAlchemy’s ORM and Core APIs through the first-party mssql+mssqlpython dialect.

If SQLAlchemy is already part of how you build, we want this to feel like a natural next step – not another thing to learn. The goal is simple: help you connect to SQL Server and Azure SQL with less setup, while keeping the tools and patterns you know.

This integration is now part of the production release, and SQLAlchemy 2.1 is the version installed by default when you run pip install sqlalchemy.

Key benefits

For SQLAlchemy users who connect to SQL Server or Azure SQL, the built-in mssql-python dialect provides:

• Simpler setup and deployment: Install the driver as a Python package without separately installing and configuring an external ODBC driver.
• A familiar development experience: Continue using SQLAlchemy ORM and Core features, including declarative models, sessions, transactions, connection pooling, and SQL expressions.
• Built-in integration: Select mssql-python with the standard mssql+mssqlpython connection URL instead of relying on a third-party dialect or custom integration.
• Modern authentication: Connect to Azure SQL with Microsoft Entra authentication, including managed identity scenarios that don’t require stored database passwords.
• Straightforward adoption: Existing mssql+pyodbc applications can generally keep their SQLAlchemy models and query patterns while updating the driver dependency and connection URL.
• Migration tooling: Continue using Alembic to manage database schema changes.

You’ve put time and care into your applications. Adopting a new driver should build on that work, not ask you to start over. This integration gives you a simpler path to SQL Server and Azure SQL while preserving the familiar SQLAlchemy programming model.

Get started

SQLAlchemy 2.1 requires Python 3.11 or later.

Install SQLAlchemy 2.1 and the mssql-python driver:

python -m pip install "SQLAlchemy[mssql-python]>=2.1.0"

Note: If you have not previously used mssql-python, confirm you have your platform-specific pre-requisites.

The mssql-python dialect uses mssql+mssqlpython as its connection URL scheme:

mssql+mssqlpython://<username>:<password>@<host>:<port>/<database>

Use URL.create() to build the URL without manually escaping special characters in credentials:

from sqlalchemy import create_engine, text
from sqlalchemy.engine import URL

url = URL.create(
    "mssql+mssqlpython",
    username="dbuser",
    password="<password>",
    host="<server>",
    port=1433,
    database="<database>",
    query={"encrypt": "yes"},
)

engine = create_engine(url)

with engine.connect() as connection:
    version = connection.execute(text("SELECT @@VERSION")).scalar_one()
    print(version)

After you create the engine, use it with the same SQLAlchemy ORM and Core APIs you already know.

Connect with Microsoft Entra authentication

For Azure SQL, you can specify a Microsoft Entra authentication method in the connection URL. For example, ActiveDirectoryDefault uses the Azure Identity credential chain:

from sqlalchemy import create_engine, text

engine = create_engine(
    "mssql+mssqlpython://@<server>.database.windows.net/<database>"
    "?authentication=ActiveDirectoryDefault&encrypt=yes"
)

with engine.connect() as connection:
    current_user = connection.execute(text("SELECT CURRENT_USER")).scalar_one()
    print(current_user)

Choose the Microsoft Entra authentication method that matches your environment. For production workloads hosted in Azure, managed identity can help you avoid storing database passwords in application configuration.

Moving from SQLAlchemy 2.0

The move from SQLAlchemy 2.0 to 2.1 is smaller than the earlier transition from 1.x to 2.0, but SQLAlchemy 2.1 includes behavioral changes that can affect existing applications. Before upgrading:

• Confirm that your application runs on Python 3.11 or later.
• Review the SQLAlchemy 2.1 migration guidance.
• Test your application’s queries, transactions, migrations, and connection-pool behavior.
• Pin dependency versions according to your deployment and update policy.

If you’re already using mssql+pyodbc, adopting mssql-python requires changing the driver portion of the connection URL and validating the application against the new driver. You don’t need to rewrite your SQLAlchemy models or replace the ORM and Core patterns in your application.

Learn more

• Follow the Microsoft Learn guide, Use mssql-python with SQLAlchemy, for ORM and Core examples, connection pooling, web framework integration, Alembic migrations, and troubleshooting.
• Read the SQLAlchemy 2.1.0 release announcement for highlights from the production release.
• Review What’s New in SQLAlchemy 2.1: Microsoft SQL Server for the upstream migration notes.

We’re excited to bring this support to developers who rely on SQLAlchemy in their everyday work. Whether you’re starting something new or taking care of an application others depend on, we hope it makes the connection to SQL Server and Azure SQL a little easier.

When you’re ready, try the new dialect in your application. We’d welcome hearing what works well and where there’s still room to improve.