Introducción a SQLAlchemy

¿Qué es SQLAlchemy?

SQLAlchemy es una librería de Python que proporciona un conjunto de herramientas de alto nivel para conectar con bases de datos relacionales, con la ventaja de que los registros de la base de datos son automáticamente transformados a objetos.

Instalación

SQLAlchemy está disponible en PyPI, entonces puedes instalarlo con pip:

pip install sqlalchemy

Y si deseas agregar como dependencia a un proyecto gestionado con uv:

uv add sqlalchemy

SQLAlchemy posee una gran cantidad de características y una basta documentación que puede ser abrumadora por la cantidad de información. Para tener una idea general de cómo utilizarlo, visita el tutorial unificado.

Conexión a una base de datos

Para conectarte a una base de datos necesitas crear un “engine”, que es el objeto que permite la conexión a la base datos. SQLAlchemy soporta una gran cantidad de bases de datos como SQLite, Postgres, MySQL/MariaDB. Python soporta de forma nativa SQLite, pero para usar otras bases de datos se requieren librerías externas que tienen los conectores necesarios.

Debes indicarle al engine la base de datos a la que vas a conectarlo. Para esto, debes indicar la URI de la base de datos, la cual depende del tipo de base de datos, conector, y forma de autenticación, que en general tiene el siguiente formato:

<protocolo>[+conector]://[usuario][:pass][@host][:puerto]/<nombre_bd>

Ejemplos

# sqlite, archivo en el mismo directorio de ejecución
sqlite:///db.sqlite3
# postgres, autenticacion directa, driver por defecto (psycopg2)
postgresql:///my_db
# postgres con psycopg3, autenticación con usuario y contraseña, host local
postgresql+psycopg://myuser:mypass@localhost/my_db

Y para crear el engine, utiliza la función create_engine().

from sqlalchemy import create_engine
 
DB_URL = "sqlite:///db.sqlite3"
engine = create_engine(DB_URL)

Tip

El parámetro echo de create_engine() te permite mostrar las instrucciones SQL que se ejecutan en la base de datos, lo cual es útil para depurar.

El engine permite ejecutar instrucciones de SQL directamente.

from sqlalchemy import text
 
with engine.connect() as conn:
    conn.execute(text("CREATE TABLE mytable (x int, y int)"))
    conn.execute(text("INSERT INTO mytable (x, y) values (1, 2)"))
 
    result = conn.execute(text("SELECT * FROM mytable"))
    for row in result:
        print(row)

Sin embargo, la ventaja de utilizar SQLAlchemy son sus capacidades de ORM, por lo que no es muy común ejecutar código SQL a través de SQLAlchemy.