SQLAlchemy

SQLAlchemy (source code) is a well-regarded database toolkit and object-relational mapper (ORM) implementation written in Python. SQLAlchemy provides a generalized interface for creating and executing database-agnostic code without needing to write SQL statements.

SQLAlchemy logo.

Why is SQLAlchemy a good ORM choice?

SQLAlchemy isn't just an ORM- it also provides SQLAlchemy Core for performing database work that is abstracted from the implementation differences between PostgreSQL, SQLite, etc. In some ways, the ORM is a bonus to Core that automates commonly-required create, read, update and delete operations.

SQLAlchemy can be used with or without the ORM features. Any given project can choose to just use SQLAlchemy Core or both Core and the ORM. The following diagram shows a few example configurations with various application software stacks and backend databases. Any of these configurations can be a valid option depending on what type of application you are coding.

Example SQLAlchemy configurations with different web frameworks.

A benefit many developers enjoy with SQLAlchemy is that it allows them to write Python code in their project to map from the database schema to the applications' Python objects. No SQL is required to create, maintain and query the database. The mapping allows SQLAlchemy to handle the underlying database so developers can work with their Python objects instead of writing bridge code to get data in and out of relational tables.

SQLAlchemy is an implementation of the object-relational mapping (ORM) concept. Learn more in the data chapter or view all topics.

How does SQLAlchemy code compare to raw SQL?

Below is an example of a SQLAlchemy model definition from the open source compare-python-web-frameworks project that uses SQLAlchemy with Flask and Flask-SQLAlchemy.

class Contact(db.Model):
    __tablename__ = 'contacts'
    id = db.Column(db.Integer, primary_key=True)
    first_name = db.Column(db.String(100))
    last_name = db.Column(db.String(100))
    phone_number = db.Column(db.String(32))

    def __repr__(self):
        return '<Contact {0} {1}: {2}>'.format(self.first_name,
                                               self.last_name,
                                               self.phone_number)

SQLAlchemy handles the table creation that otherwise we would have had to write a create table statement like this one to do the work:

CREATE TABLE CONTACTS(
   ID INT PRIMARY KEY        NOT NULL,
   FIRST_NAME     CHAR(100)  NOT NULL,
   LAST_NAME      CHAR(100)  NOT NULL,
   PHONE_NUMBER   CHAR(32)   NOT NULL,
);

By using SQLAlchemy in our Python code, all records can be obtained with a line like contacts = Contact.query.all() instead of a plain SQL such as SELECT * FROM contacts. That may not look like much of a difference in syntax but writing the queries in Python is often faster and easier for many Python developers once multiple tables and specific filtering on fields for queries have to be written. In addition, SQLAlchemy abstracts away idiosyncratic differences between database implementations in SQLite, MySQL and PostgreSQL.

SQLAlchemy Extensions, Plug-ins and Related Libraries

Take a look at the SQLAlchemy extensions, plug-ins and related libraries page for a curated list of useful code libraries to use with SQLAlchemy.

Using SQLAlchemy with Web Frameworks

There is no reason why you cannot use the SQLAlchemy library in any application that requires a database backend. However, if you are building a web app with Flask, Bottle or another web framework then take a look at the following extensions. They provide some glue code along with helper functions that can reduce the boilerplate code needed to connect your application's code with the SQLAlchemy library.

SQLAlchemy resources

The best way to get comfortable with SQLAlchemy is to dig in and write a database-driven application. The following resources can be helpful if you are having trouble getting started or are starting to run into some edge cases.

SQLAlchemy compared to other ORMs

SQLAlchemy is one of many Python object-relational mapper (ORM) implementations. Several open source projects and articles are listed here to make it a bit easier to understand the differences between these implementations.

Open source code for learning SQLAlchemy

Many open source projects rely on SQLAlchemy. A great way to learn how to properly work with this tool is to read the code that shows how those projects use SQLAlchemy. This section alphabetically lists these code examples by class and function in the SQLAlchemy code base.

SQLAlchemy: Extensions, Plug-ins and Related Libraries & Example Projects and Code

sqlalchemy.databases mysql

sqlalchemy.dialects mssql, mysql, oracle, postgresql, sqlite

sqlalchemy.dialects.mysql pymysql

sqlalchemy.dialects.postgresql ARRAY, BIGINT, BIT, DOUBLE_PRECISION, ExcludeConstraint, INTEGER, JSON, TSVECTOR, array, json, pypostgresql

sqlalchemy.dialects.postgresql.base PGCompiler, PGIdentifierPreparer, PGTypeCompiler

sqlalchemy.dialects.postgresql.psycopg2 PGDialect_psycopg2

sqlalchemy.dialects.sqlite pysqlite

sqlalchemy.engine Connection, Engine, create_engine, default, url

sqlalchemy.engine.default DefaultDialect

sqlalchemy.engine.interfaces ExecutionContext

sqlalchemy.engine.result ResultMetaData, RowProxy

sqlalchemy.engine.strategies EngineStrategy, MockEngineStrategy

sqlalchemy.engine.url make_url

sqlalchemy.events SchemaEventTarget

sqlalchemy.exc ArgumentError, DataError, DatabaseError, IntegrityError, InvalidRequestError, NoInspectionAvailable, NoSuchTableError, OperationalError, ProgrammingError, UnsupportedCompilationError

sqlalchemy.ext compiler

sqlalchemy.ext.associationproxy AssociationProxy

sqlalchemy.ext.automap automap_base

sqlalchemy.ext.compiler compiles

sqlalchemy.ext.declarative DeclarativeMeta, declarative_base

sqlalchemy.ext.hybrid HYBRID_METHOD, HYBRID_PROPERTY, hybrid_method, hybrid_property

sqlalchemy.ext.mutable Mutable

sqlalchemy.inspection inspect

sqlalchemy.orm ColumnProperty, CompositeProperty, Load, Mapper, Query, RelationshipProperty, Session, SynonymProperty, aliased, attributes, backref, class_mapper, column_property, composite, interfaces, mapper, mapperlib, object_mapper, object_session, query, relationship, session, sessionmaker, strategies

sqlalchemy.orm.attributes InstrumentedAttribute, QueryableAttribute, flag_modified

sqlalchemy.orm.collections InstrumentedList

sqlalchemy.orm.exc NoResultFound, UnmappedClassError, UnmappedInstanceError

sqlalchemy.orm.interfaces MapperProperty, PropComparator

sqlalchemy.orm.mapper Mapper

sqlalchemy.orm.properties ColumnProperty, RelationshipProperty

sqlalchemy.orm.query Query, QueryContext

sqlalchemy.orm.relationships RelationshipProperty

sqlalchemy.orm.session Session, object_session

sqlalchemy.orm.util AliasedClass, AliasedInsp, identity_key

sqlalchemy.pool NullPool, StaticPool

sqlalchemy.schema CheckConstraint, Column, CreateIndex, CreateTable, DDLElement, ForeignKey, ForeignKeyConstraint, Index, PrimaryKeyConstraint, Table

sqlalchemy.sql ClauseElement, Select, column, expression, extract, functions, operators, schema, select, sqltypes, table

sqlalchemy.sql.compiler SQLCompiler

sqlalchemy.sql.elements ColumnElement, Label

sqlalchemy.sql.expression ClauseElement, ColumnClause, ColumnElement, Executable, FunctionElement, UnaryExpression

sqlalchemy.sql.functions FunctionElement, GenericFunction

sqlalchemy.sql.naming conv

sqlalchemy.sql.schema Column, SchemaItem

sqlalchemy.sql.sqltypes NULLTYPE, NullType

sqlalchemy.sql.util ClauseAdapter

sqlalchemy.sql.visitors traverse

sqlalchemy.types BOOLEAN, Boolean, DATE, DATETIME, Date, DateTime, Enum, FLOAT, Float, INTEGER, Integer, Interval, NULLTYPE, NullType, String, TEXT, TIME, Text, Time, TypeEngine, UserDefinedType, to_instance

sqlalchemy.util OrderedDict, OrderedSet, set_creation_order, symbol, topological

sqlalchemy.util.langhelpers public_factory, symbol

What would you like to learn about building Python web apps?

Tell me about standard relational databases.

What're these NoSQL data stores hipster developers keep talking about?

I want to know about working with data in Python.


Matt Makai 2012-2022