Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 37 ยท Getting Started

What Is SQLAlchemy?

Meet SQLAlchemy, the Python toolkit that talks to relational databases through Core and the ORM. Learn what it does, why people use it, and what runs on this site.

Almost every real application keeps data in a relational database, and Python needs a way to talk to it. You can write SQL strings by hand and send them through a driver such as sqlite3 or psycopg, but that gets tedious: you build strings, bind parameters, convert rows into objects, and rewrite things when you move from one database to another. SQLAlchemy is the library most Python developers reach for to remove that friction.

SQLAlchemy is two things in one package. Core is a SQL toolkit: you describe tables and build SELECT, INSERT, UPDATE and DELETE statements as Python objects. The ORM (object-relational mapper) sits on top of Core: you map ordinary Python classes to tables, and rows become objects you can change and save. This tutorial teaches both, in the modern 2.0 style that all current documentation uses.

What runs here. Every <TryIt> in this tutorial runs real SQLAlchemy 2.0 inside your browser (Pyodide), against an in-memory SQLite database. Nothing leaves your machine. PostgreSQL, MySQL and other servers cannot run in a browser, so lessons that mention them show read-only snippets and say so. Alembic (migrations) also runs for real, in chapter 7.

Why not just write SQL?

Raw SQL is fine, and SQLAlchemy never forbids it. What the library adds is a set of things you would otherwise rebuild yourself:

  • Composable queries. Add a filter conditionally by calling .where() again, instead of gluing strings together.
  • Safe parameters. Values are always sent as bound parameters, which blocks SQL injection by default.
  • Portability. The same Python code is rendered into the dialect of SQLite, PostgreSQL, MySQL, SQL Server or Oracle.
  • Connection pooling and transactions managed for you.
  • An object model (the ORM) that tracks changes and writes only what changed.

SQLAlchemy in one picture

Core Tables, SQL expressions, engines
ORM Classes mapped to tables
Dialects SQLite, PostgreSQL, MySQL...

Core is the foundation. The ORM is built on it.

1 / 2

Your first look

Here is the smallest useful program. It creates an in-memory database, runs one SQL statement, and prints the version of the library. Do not worry about the details yet: each piece gets its own lesson.

Python Hello, SQLAlchemy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

create_engine() builds an object that knows how to reach a database. engine.connect() borrows a connection, and text() marks a string as SQL. The result is a Row object whose columns you read as attributes.

The same job in three styles

To get a feel for the layers, here is the same tiny task (store two languages and read them back) at each level. Run it and compare how much you type as you move up.

Python Raw driver, Core and ORM

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice what stays the same: a database, tables, rows. What changes is who builds the SQL and what you get back: tuples from the driver, Row objects from Core, real Lang instances from the ORM.

Where SQLAlchemy fits in a project

SQLAlchemy is not a web framework. You will find it behind Flask apps (through Flask-SQLAlchemy), FastAPI services, command-line tools, data pipelines and notebooks. It pairs with Alembic for schema migrations (chapter 7) and with any database driver you like. Django has its own ORM, so SQLAlchemy is the choice when you want more control, more databases, or no framework at all.

flowchart TB
    APP["Your application"] --> ORM["ORM: classes and Session"]
    APP --> CORE["Core: tables and SQL expressions"]
    ORM --> CORE
    CORE --> ENG["Engine and connection pool"]
    ENG --> DRV["DBAPI driver (sqlite3, psycopg, ...)"]
    DRV --> DB[("Database")]

Every layer you use is built on the one below it. You can enter at any level.

A word on versions

SQLAlchemy 2.0 changed the recommended API: select() instead of session.query(), typed Mapped[...] columns, explicit transactions. Older tutorials still show 1.x patterns. This course teaches 2.0 only, and mentions the old forms only when you are likely to meet them in existing code.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about Core and the ORM is correct?

    The ORM uses Core to build and run SQL. Both ship in the same package and you can mix them freely.
  2. 2. What does text() do in text("SELECT 1")?

    text() wraps a plain SQL string so the engine accepts it as an executable statement.
  3. 3. Why does SQLAlchemy help against SQL injection?

    Bound parameters keep data separate from SQL text, so user input cannot change the meaning of a query.
  4. 4. Which API style does this tutorial teach?

    SQLAlchemy 2.0 is the current API, and all lessons use it.

Summary

  • SQLAlchemy is a Python toolkit for relational databases, made of Core (SQL expressions) and the ORM (mapped classes).
  • It builds safe, portable SQL, pools connections and manages transactions.
  • Every example here runs for real in your browser against in-memory SQLite.
  • This course uses the modern 2.0 API.

Next: Installing SQLAlchemy and Your First Program