Skip to content

How to Execute Raw SQL in SQLAlchemy

In the realms of data science and web development, the use of databases is inevitable. These powerful systems hold and manage significant chunks of data, making them invaluable in a world that's heavily dependent on information. Python, a prominent programming language in these domains, leverages various tools to communicate with databases, and one such tool is SQLAlchemy. While SQLAlchemy's Object-Relational Mapping (ORM) layer is a boon for developers seeking high-level abstractions for their database operations, there are occasions where executing raw SQL queries is more effective or intuitive. This article offers a deep dive into the execution of raw SQL queries within SQLAlchemy, providing concrete code examples for clarity and understanding.

Understanding SQLAlchemy: An Overview

To comprehend the concept of executing raw SQL in SQLAlchemy, we first need to grasp what SQLAlchemy is. As a SQL toolkit, SQLAlchemy provides a suite of tools for Python applications to interact with SQL databases. It offers a full suite of well known enterprise-level persistence patterns, designed for efficient and high-performing database access.

SQLAlchemy aims to accommodate both high and low-level database operations. Its two main components, SQLAlchemy Core and SQLAlchemy ORM, deal with these operations. The SQLAlchemy Core is centered around SQL abstraction, schema metadata, connection pooling, type coercion, and more. It provides a low-level SQL interface for Python, enabling developers to interact with the database in a Pythonic way. On the other hand, SQLAlchemy ORM is a high-level, data-centric API that provides domain model patterns, encapsulating databases and tables as Python classes and objects.

The Power and Potential of Raw SQL

With the background of SQLAlchemy and its components, let's turn our focus to raw SQL queries. Raw SQL refers to SQL statements and queries written as simple, plain text strings. As a database language, SQL (Structured Query Language) allows us to access and manipulate databases. Raw SQL queries are often utilized when there's a need to execute complex operations where the ORM abstraction might seem restricting.

These raw SQL queries are exceptionally useful when a particular database operation is difficult to express through the ORM layer or when the ORM syntax is less intuitive than the equivalent SQL operation. Moreover, developers who are more comfortable writing SQL queries may find raw SQL in SQLAlchemy an excellent way to get the best of both worlds—the power of SQL with the convenience of Python.

The Art of Executing Raw SQL in SQLAlchemy

In SQLAlchemy, raw SQL can be executed directly using the execute() method offered by both the Engine and Session objects.

Employing the Engine's Execute Method

Let's take a look at an example of executing raw SQL using the engine.execute() method:

from sqlalchemy import create_engine
engine = create_engine('sqlite:///:memory:')
result = engine.execute("SELECT * FROM users WHERE age >= :age", {'age': 21})
for row in result:

In the code above, we are executing a raw SQL query that fetches all users aged 21 and above. The create_engine() function establishes a connection with the database (in this case, an in-memory SQLite database). The execute() method on the engine instance then takes the SQL query as a string and executes it against the database.

Harnessing the Session's Execute Method

As an alternative, raw SQL can also be executed using the session.execute() method:

from sqlalchemy.orm import Session
session = Session(bind=engine)
 = session.execute("SELECT * FROM users WHERE age >= :age", {'age': 21})
for row in result:

This example appears quite similar to the previous one. However, there's a subtle yet crucial distinction. The session.execute() method ensures that the queries are managed by a transaction. In the parlance of databases, a transaction is a sequence of operations performed as a single logical unit of work. Thus, the session allows multiple queries in the same request to be committed or rolled back together, preventing inconsistencies and improving the reliability of the system. Conversely, using engine.execute() can leave the system more prone to bugs that might lead to data corruption.

The Craft of Committing Transactions

When executing raw SQL queries, it's essential to understand the process of committing transactions. This becomes significant, especially when you are performing operations that modify the data, such as INSERT, UPDATE, or DELETE. SQLAlchemy, through its session management, allows control over when these changes should be made permanent.

Here's an example:

from sqlalchemy import text
with session.begin():
        text("UPDATE users SET age = :new_age WHERE age = :old_age"),
        {'new_age': 30, 'old_age': 20}

In the code above, we first start a new transaction using session.begin(). This transaction includes the raw SQL query that updates the age of all users from 20 to 30. The transaction is then automatically committed at the end of the with block. In case an exception occurs during the execution of the query, the transaction is rolled back, keeping the database's state consistent.

The Vital Role of Parameterization

It's worth noting that raw SQL queries may sometimes be vulnerable to SQL injection attacks, a common web security vulnerability. Parameterization is a technique to prevent such attacks. SQLAlchemy's text() function helps parameterize raw SQL queries.

Here's an illustrative example:

from sqlalchemy import text
query = text("SELECT * FROM users WHERE name = :name")
result = session.execute(query, {'name': 'Alice'})

In the code snippet above, the :name inside the query string is a bind parameter. When the execute() function is called, we pass a dictionary that maps these bind parameters to their respective values. This feature ensures that the data is correctly escaped, mitigating the risk of SQL injection.

Mastering Inline Views and Joins

Complex queries often require the use of inline views and joins. Inline views are subqueries in the FROM clause, enabling us to use the result of a query as a table. Joins, on the other hand, combine rows from two or more tables based on related columns. Here's a raw SQL example featuring an inline view and a join:

query = text("""
SELECT, counts.invoice_count
FROM users
JOIN (SELECT user_id, COUNT(*) as invoice_count FROM invoices GROUP BY user_id) AS counts
ON = counts.user_id
WHERE counts.invoice_count > :count
result = session.execute(query, {'count': 10})

This query fetches all users who have more than 10 invoices. The inline view here is the counts table, which is the result of the subquery that calculates the number of invoices for each user.



The ability to execute raw SQL in SQLAlchemy provides the flexibility to deal with complex queries while preserving the convenience and security of using a high-level language like Python. This approach combines the full capabilities of SQL with Python's usability, giving developers the edge in crafting efficient, intuitive, and secure database operations.

Frequently Asked Questions

Q1: How do I run a raw SQL query in SQLAlchemy?

You can use either the session.execute() or engine.execute() methods to run raw SQL queries in SQLAlchemy. The session.execute() method is recommended as it ensures the queries are properly managed by a transaction.

Q2: How do I perform a SELECT query in SQLAlchemy?

To perform a SELECT query, pass the raw SQL query string to the execute() method. For example, result = session.execute("SELECT * FROM users") will fetch all rows from the users table.

Q3: How can I prevent SQL injection when using raw SQL queries in SQLAlchemy?

To prevent SQL injection when using raw SQL queries in SQLAlchemy, utilize parameterization by passing query parameters as bind values, ensuring proper escaping and validation of user input.