David's Blog

Using SQLAlchemy in Python A Comprehensive Guide

By David Li on 2023-10-24T03:02:10.000Z

Using SQLAlchemy in Python: A Comprehensive Guide

In this article, we will explore SQLAlchemy, a powerful and versatile Object Relational Mapper (ORM) for Python that makes database interactions easy and efficient. We will learn how to install and use SQLAlchemy, create a simple application, and understand some of its most powerful features.

Table of Contents

  1. Introduction to SQLAlchemy
  2. Installation
  3. Basic Usage
    1. Creating Models
    2. Creating and Configuring the Engine
    3. Creating and Using Sessions
    4. Inserting Data
    5. Querying Data
    6. Updating Data
    7. Deleting Data
  4. Advanced Features
    1. Relationships
    2. Transactions
    3. Inheritance
  5. Conclusion

1. Introduction to SQLAlchemy

SQLAlchemy is a popular Python library that provides a full suite of well-organized tools to interact with relational databases. It simplifies the process of writing SQL queries and performing CRUD operations by providing a high-level, Pythonic API.

One of the main advantages of using SQLAlchemy is that it allows developers to write database-agnostic code. This means that you can switch between different SQL databases (such as PostgreSQL, MySQL, SQLite) with minimal code changes.

2. Installation

To install SQLAlchemy, simply run the following command:

pip install sqlalchemy

3. Basic Usage

3.1. Creating Models

The first step in using SQLAlchemy is to define your data models. Models are Python classes that represent database tables. They define the structure of the tables and the relationships between them. Here’s a simple example:

from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    age = Column(Integer)

    def __repr__(self):
        return f"<User(name={self.name}, age={self.age})>"

In this example, we define a User model with three columns: id, name, and age. The __tablename__ attribute is used to specify the name of the database table.

3.2. Creating and Configuring the Engine

The next step is to create an “engine” that connects to your database. The engine is responsible for managing database connections and translating Python code into SQL commands.

To create an engine, you need to provide a connection string, which specifies the database type, credentials, and other options. Here’s an example:

from sqlalchemy import create_engine

## Replace this connection string with your own
connection_string = 'sqlite:///example.db'

engine = create_engine(connection_string)

In this example, we create a SQLite database called example.db. For other databases, the connection string format will be different. You can find more information about connection strings in the SQLAlchemy documentation.

Once you have created an engine, you can use it to create the tables defined by your models:


3.3. Creating and Using Sessions

To interact with the database, you need to create a “session”. A session is an object that manages the state of your objects and keeps track of any pending changes.

To create a session, you can use the sessionmaker function:

from sqlalchemy.orm import sessionmaker

Session = sessionmaker(bind=engine)
session = Session()

3.4. Inserting Data

To insert data into the database, you can create instances of your models and add them to the session. Here’s an example:

new_user = User(name="Alice", age=30)

In this example, we create a new User object, add it to the session, and then call session.commit() to save the changes to the database.

3.5. Querying Data

To query data from the database, you canuse the session.query() method. This method returns a Query object that allows you to filter, order, and group the results. Here’s an example:

## Get all users
users = session.query(User).all()

## Get a specific user by ID
user = session.query(User).get(1)

## Get users with a specific name
users = session.query(User).filter_by(name="Alice").all()

## Get users with a specific age
users = session.query(User).filter(User.age == 30).all()

## Get users sorted by age, ascending
users = session.query(User).order_by(User.age).all()

In this example, we demonstrate various ways to query the User model. You can combine filters, ordering, and other options to create complex queries.

3.6. Updating Data

To update data in the database, you can modify the attributes of your model instances and then call session.commit() to save the changes. Here’s an example:

## Update a specific user's age
user = session.query(User).get(1)
user.age = 35

In this example, we update the age of a User object and then commit the changes to the database.

3.7. Deleting Data

To delete data from the database, you can use the session.delete() method. Here’s an example:

## Delete a specific user by ID
user = session.query(User).get(1)

In this example, we delete a User object from the database and then commit the changes.

4. Advanced Features

4.1. Relationships

SQLAlchemy allows you to define relationships between your models using the relationship() function. This makes it easy to navigate between related objects and perform queries that involve multiple tables. Here’s an example:

from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship

class Post(Base):
    __tablename__ = 'posts'

    id = Column(Integer, primary_key=True)
    title = Column(String)
    content = Column(String)
    user_id = Column(Integer, ForeignKey('users.id'))

    author = relationship("User", back_populates="posts")

User.posts = relationship("Post", order_by=Post.id, back_populates="author")


In this example, we define a Post model with a foreign key to the User model. We then create a relationship between the two models using the relationship() function.

4.2. Transactions

SQLAlchemy provides built-in support for transactions, which allow you to group multiple operations into a single, atomic unit of work. To use transactions, you can use the session.begin() method:

## Start a new transaction

    ## Perform some operations
    user1 = User(name="Bob", age=25)
    user2 = User(name="Carol", age=28)
    session.add_all([user1, user2])

    ## Commit the transaction
    ## Roll back the transaction in case of errors

In this example, we start a new transaction using session.begin(), perform some operations, and then commit the transaction using session.commit(). If an error occurs, we roll back the transaction using session.rollback().

4.3. Inheritance

SQLAlchemy supports various inheritance strategies, including single table inheritance, concrete table inheritance, and joined table inheritance. This allows you to model complex hierarchies of objects and reuse code between related models. Here’s an example using single table inheritance:

from sqlalchemy import Enum

class Animal(Base):
    __tablename__ = 'animals'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    type = Column(Enum("cat", "dog", name="animal_type"), nullable=False)

    __mapper_args__ = {
        'polymorphic_identity': 'animal',
        'polymorphic_on': type

class Cat(Animal):
    __mapper_args__ = {
        'polymorphic_identity': 'cat',

    meow_sound = Column(String)

class Dog(Animal):
    __mapper_args__ = {
        'polymorphic_identity': 'dog',

    bark_sound = Column(String)


In this example, we define a base Animal model and two subclasses, Cat and Dog. We use single table inheritance to store

© Copyright 2023 by Astro Tech Blog. Built with ♥ by FriendlyUser. Last updated on 2023-05-29.