Todo lo que necesitas saber sobre SQLAlchemy
¿Qué es SQL Alchemy?
SQLAlchemy es un Object-Relational Mapper/Mapping-tool, o un ORM, es una librería que los desarrolladores utilizan para crear bases de datos y manipular sus datos sin la necesidad de conocer/usar SQL.
Existen otras alternativas en Python como Peewee, y otros lenguajes tienen sus propios ORMs, como PHP Eloquent o Java Hibernate.
¿Por qué usar un ORM?
Los ORM han ganado popularidad debido a que lidiar con el lenguaje SQL directamente requiere de mucho esfuerzo en la mayoría de los casos. El objetivo del ORM entonces es simplificar el mantenimiento de tus datos. Esto se hace creando objetos para tratar con las interacciones de la base de datos.
Básicamente, con ORM no tendrás que escribir SQL otra vez (el 95% del tiempo) y podrás trabajar con objetos.
Por ejemplo:
Para insertar un usuario con SQL tienes que escribir:
1INSERT INTO user (name, last_name) VALUES ('Bob', 'Ross');
Con un ORM tu código sigue siendo un código familiar como este:
1user = User() 2user.name = "Bob" 3user.last_name = "Ross" 4 5# Agrega el user a la base de datos 6db.session.add(user) 7 8# Parecido al commit de Git, lo que hace esta función es guardar todos los cambios que hayas hecho 9db.session.commit()
Basta con que utilices la función db.session.commit() y todo lo que hayas hecho con tu código se traducirá a código de lenguaje SQL.
Revisemos las operaciones más típicas que se pueden realizar sobre una base de datos
Importando e inicializando la aplicación
Para utilizar SQL Alchemy necesitamos instalar la librería flask de Python. Una vez lo hayamos hecho, estableceremos una conexión a la base de datos y definiremos el objeto db, que es lo más importante para empezar a trabajar con ella. En la documentación encontraremos 2 métodos para implementar esta librería: el tradicional (proyectos legacy) y el moderno (recomendado)
1from flask import Flask 2from sqlalchemy.orm import Mapped, mapped_column # Sólo necesario en el método moderno 3from flask_sqlalchemy import SQLAlchemy 4 5app = Flask(__name__) 6app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:////tmp/test.db" 7db = SQLAlchemy(app)
Creando nuestra base de datos
El primer paso sería definir nuestro modelo.
- Método Tradicional
1class Person(db.Model): 2 # Aquí definimos el nombre de la tabla "Person" 3 __tablename__ = "person" # Es opcional debiado a que usa el nombre de la clase por defecto. 4 5 # Ten en cuenta que cada columna es también un atributo normal de primera instancia de Python. 6 id = db.Column(db.Integer, primary_key=True) 7 name = db.Column(db.String(250), nullable=False) 8 9 # El método serialize convierte el objeto en un diccionario 10 def serialize(self): 11 return { 12 "id": self.id, 13 "name": self.name, 14 }
- Método Moderno
1class Person(Base): 2 # Aquí definimos el nombre de la tabla "Person" 3 __tablename__ = "person" # Es opcional debiado a que usa el nombre de la clase por defecto. 4 5 # Ten en cuenta que cada columna es también un atributo normal de primera instancia de Python. 6 id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True) 7 name: Mapped[str] = mapped_column(unique=False, nullable=False) 8 9 # El método serialize convierte el objeto en un diccionario 10 def serialize(self): 11 return { 12 "id": self.id, 13 "name": self.name 14 }
INSERT: Insertando un registro en la base de datos
Para insertar un registro en la base de datos, es necesario, primero, contar con la instancia que se desea añadir. A continuación, agregarlo a la sesión de la base de datos y completar la acción con un commit. En el siguiente código se visualiza esta funcionalidad (reemplaza <username_value> y <email_value> con los valores reales que desees agregar):
1person = Person(username = <username_value>, email = <email_value>) 2db.session.add(person) 3db.session.commit()
SELECT: Buscando o recuperando registros de la base de datos
Hay 3 formas para obtener información de la base de datos:
- Obtener todos los registros de una tabla/modelo en particular usando
MyModel.query.all() - Obtener un único registro en función de su clave principal mediante
MyModel.query.get(id) - Obtener un grupo de registros en función de una consulta
Person.query.filter_by(arg1=value, arg2=value, ...)
1# Obtener todos los registros de una tabla/modelo en particular, en este caso, de Person 2all_people = Person.query.all() 3all_people = list(map(lambda x: x.serialize(), all_people)) 4 5# Obtener un único registro en función de su clave principal, que en este caso es el "id" de la persona (solo funciona con las claves principales) 6person = Person.query.get(3) 7 8# Obtener un grupo de registros en función de una consulta, en este caso, el string "alex" en la columna "name" 9all_people = Person.query.filter_by(name = "alex") 10all_people = list(map(lambda x: x.serialize(), all_people))
A partir de la versión SQLAlchemy 2.x estas consultas se hacen con excute
1from sqlalchemy import select 2 3# Obtener todos los registros 4all_people = db.session.execute(select(Person)).scalars().all() 5 6# Obtener un registro por ID 7person = db.session.get(Person, 3) # Método directo recomendado 8# Alternativa con execute: 9person = db.session.execute(select(Person).where(Person.id == 3)).scalar_one_or_none() 10 11# Filtrar registros 12people = db.session.execute( 13 select(Person).where(Person.name == "alex") 14).scalars().all() 15 16# Filtros avanzados 17from sqlalchemy import or_ 18people = db.session.execute( 19 select(Person).where(or_(Person.name == "alex", Person.age > 25)) 20).scalars().all()
Diferencias entre los métodos query y db.session.execute()
Tabla comparativa de operaciones comunes
| Operación | Método tradicional (query) | Método moderno (db.session.execute()) |
|---|---|---|
| Todos los registros | Model.query.all() | db.session.execute(select(Model)).scalars().all() |
| Obtener por ID | Model.query.get(id) | db.session.get(Model, id)o db.session.execute(select(Model).where(Model.id == id)).scalar_one() |
| Filtros simples | Model.query.filter_by(name="x") | db.session.execute(select(Model).where(Model.name == "x")) |
| Filtros complejos | Model.query.filter(or_(...)) | db.session.execute(select(Model).where(or_(...))) |
| Primer resultado | Model.query.first() | db.session.execute(select(Model).limit(1)).scalar_one() |
| Ordenamiento | Model.query.order_by(Model.name.desc()) | db.session.execute(select(Model).order_by(Model.name.desc())) |
| Paginación | Model.query.paginate(page=1, per_page=10) | db.session.execute(select(Model).offset(0).limit(10)) |
ℹ️ Nota: Aunque
querysigue funcionando, se recomienda migrar al nuevo estilo para futura compatibilidad.
DELETE: Eliminando un registro de la base de datos
Para eliminar un registro de la base de datos es necesario seleccionar previamente la instancia que se desee borrar (a través de su clave primaria, el id) y eliminarla utilizando db.session.delete(person), de acuerdo al siguiente ejemplo:
- Método tradicional
1person = Person.query.get(3) 2db.session.delete(person) 3db.session.commit()
- Método moderno
1person = db.session.get(Person, 3) 2db.session.delete(person) 3db.session.commit()
UPDATE: Actualizar un registro
Para modificar un registro, hay que seleccionar previamente el mismo de la base de datos, luego puedes trabajar con él cambiando sus propiedades y hacer commit nuevamente, según el siguiente ejemplo:
- Método tradicional
1person = Person.query.get(3) 2person.name = "Bob" 3db.session.commit()
- Método moderno
1person = db.session.get(Person, 3) 2person.name = "Bob" 3db.session.commit()
Transacciones
Una transacción es una secuencia de operaciones (como INSERT, UPDATE, SELECT) realizadas en tu base de datos. Para que una transacción esté completa, todas las operaciones deben ser exitosas. Si una operación falla, toda la transacción falla.
Todas las transacciones deben asegurar 4 propiedades principales (conocidas como propiedades ACID): Atomicidad, Consistencia, Aislamiento y Durabilidad.
Una transacción termina con COMMIT o ROLLBACK.
COMMIT: session.commit()
El comando COMMIT se usa para guardar de manera permanente los cambios realizados en una transacción dentro de la base de datos.
Cuando usas INSERT, UPDATE o DELETE, los cambios realizados con estos comandos no son permanentes, los cambios hechos pueden deshacerse o, dicho con otras palabras, podemos volver atrás.
Sin embargo, cuando usas el comando COMMIT los cambios en tu base de datos serán permanentes.
ROLLBACK: session.rollback()
El comando ROLLBACK restaura tu base de datos hasta tu último COMMIT. También puedes usarlo con el comando SAVEPOINT para saltar a un punto que hayas guardado durante una transacción en curso.
Del mismo modo, si usas UPDATE para hacer cambios en tu base de datos, puedes deshacerlos usando el comando ROLLBACK, pero solo si aún no has usado el comando COMMIT de esta forma:
1db.session.rollback()
SAVEPOINT: session.begin_nested()
El comando SAVEPOINT se usa para guardar temporalmente una transacción para así poder volver a cierto punto utilizando el comando ROLLBACK si así lo necesitas. Puedes usarlo así:
1db.session.begin_nested()
Este comando se puede llamar muchas veces, y con cada llamada se establece un punto de control llamado checkpoint y que lleva asociado un identificador único.
Pongamos, por ejemplo, el caso de que queramos preparar una pizza y preparemos una base de datos en la que introducir los ingredientes que lleva. La base de esta pizza que queremos preparar lleva tres ingredientes: mozzarella, tomate y aceitunas. Nuestra tabla se va a llamar 'Pizza' y, después de insertar los ingredientes, se vería de la siguiente manera:
Además, tenemos una lista de ingredientes extra que podemos añadir: escogemos carne primero, pero luego cambiamos de parecer y queremos reemplazarla por champiñones. También añadiremos pepperoni y bacon. Veamos como se haría esta transacción:
1# Supongamos que ya tenemos los ingredientes base añadidos con anterioridad 2 3# Ahora insertamos un nuevo ingrediente en la pizza, la carne 4ingredient = Ingredient() 5ingredient.name = "meat" 6ingredient.id = 4 7db.session.add(ingredient) 8 9# Ahora hacemos COMMIT y lo guardamos en la base de datos, de tal forma que fijamos el ingrediente en la Pizza 10db.session.commit() 11 12# Reemplazamos el cuarto ingrediente, que antes era la carne, por los champiñones 13ingredient = Ingredient.query.get(4) 14ingredient.name = "mushrooms" 15db.session.commit() 16 17# Guardamos un "checkpoint" 18checkpoint_a = db.session.begin_nested() 19 20# Añadimos pepperoni en la pizza 21ingredient = Ingredient() 22ingredient.name = "pepperoni" 23db.session.add(ingredient) 24db.session.commit() 25 26# Un último "checkpoint" antes de añadir el bacon 27checkpoint_b = db.session.begin_nested() 28 29# Insertamos el bacon 30ingredient = Ingredient() 31ingredient.name = "bacon" 32db.session.add(ingredient)
Ahora nuestra 'Pizza' tiene los siguientes ingredientes:
Sin embargo, antes de meterla en el horno hemos decidido que no queremos bacon, así que usamos el rollback:
1checkpoint_b.rollback() 2# Vuelve atrás, hasta el checkpoint B, donde no se incluye el bacon
Finalmente, nuestra 'Pizza' se ve así:
... Me ha dado hambre después de leer esta lección ¿¿tú no tienes hambre??
Relaciones en SQLAlchemy:
Las relaciones permiten conectar modelos/tablas entre sí, reflejando cómo interactúan los datos en tu base de datos. SQLAlchemy ofrece 3 tipos principales de relaciones, cada una con su sintaxis tradicional (v1.x) y moderna (v2.x+).
1. Relación Uno a Muchos (One-to-Many)
¿Cuándo debo usarla?
Cuando un registro en Tabla A puede tener múltiples registros asociados en Tabla B.
- Método Tradicional (query)
1class User(db.Model): 2 id = db.Column(db.Integer, primary_key=True) 3 posts = db.relationship('Post', backref='author') 4 5class Post(db.Model): 6 id = db.Column(db.Integer, primary_key=True) 7 user_id = db.Column(db.Integer, db.ForeignKey('user.id'))
- Método Moderno (SQLAlchemy 2.x)
1class User(db.Model): 2 id: Mapped[int] = mapped_column(primary_key=True) 3 posts: Mapped[List["Post"]] = relationship(back_populates="author") 4 5class Post(db.Model): 6 id: Mapped[int] = mapped_column(primary_key=True) 7 user_id: Mapped[int] = mapped_column(ForeignKey("user.id")) 8 author: Mapped["User"] = relationship(back_populates="posts")
2. Relación Muchos a Muchos (Many-to-Many)
- Método Tradicional
1tags = db.Table('tags', 2 db.Column('post_id', db.Integer, db.ForeignKey('post.id')), 3 db.Column('tag_id', db.Integer, db.ForeignKey('tag.id')) 4) 5 6class Post(db.Model): 7 id = db.Column(db.Integer, primary_key=True) 8 tags = db.relationship('Tag', secondary=tags, backref=db.backref('posts', lazy='dynamic')) 9 10class Tag(db.Model): 11 id = db.Column(db.Integer, primary_key=True)
- Método Moderno
1class Post(db.Model): 2 id: Mapped[int] = mapped_column(primary_key=True) 3 tags: Mapped[List["Tag"]] = relationship(secondary="post_tag", back_populates="posts") 4 5class Tag(db.Model): 6 id: Mapped[int] = mapped_column(primary_key=True) 7 posts: Mapped[List["Post"]] = relationship(secondary="post_tag", back_populates="tags") 8 9post_tag = Table( 10 "post_tag", 11 db.metadata, 12 Column("post_id", ForeignKey("post.id")), 13 Column("tag_id", ForeignKey("tag.id")) 14)
¿Cuándo usarla?
Cuando necesitas relaciones complejas donde ambas tablas pueden tener múltiples registros vinculados entre sí.
3. Relación Uno a Uno (One-to-One)
- Método Tradicional
1class User(db.Model): 2 id = db.Column(db.Integer, primary_key=True) 3 profile = db.relationship('Profile', uselist=False, backref='user') 4 5class Profile(db.Model): 6 id = db.Column(db.Integer, primary_key=True) 7 user_id = db.Column(db.Integer, db.ForeignKey('user.id'))
- Método Moderno
1class User(db.Model): 2 id: Mapped[int] = mapped_column(primary_key=True) 3 profile: Mapped["Profile"] = relationship(back_populates="user") 4 5class Profile(db.Model): 6 id: Mapped[int] = mapped_column(primary_key=True) 7 user_id: Mapped[int] = mapped_column(ForeignKey("user.id")) 8 user: Mapped["User"] = relationship(back_populates="profile")
¿Cuándo usarla?
Cuando un registro en Tabla A debe vincularse con exactamente un registro en Tabla B.
Tabla Comparativa
| Relación | Método Tradicional | Método Moderno | Ventajas del Método Moderno |
|---|---|---|---|
| Uno a Muchos | relationship('Post', backref='author') | Mapped[List["Post"]] = relationship(back_populates="author") | Tipado explícito, mejor soporte IDE |
| Muchos a Muchos | Tabla secundaria separada, backref con lazy loading | Tabla como objeto, back_populates bidireccional | Mayor claridad, control preciso de tipos |
| Uno a Uno | uselist=False en relationship | Mapped["Profile"] sin lista | Sintaxis más intuitiva, mejor documentación |
| Configuración | Implícito en backref | Explícito con back_populates | Relaciones más claras y mantenibles |
| Tipado | Sin soporte nativo | Tipado con Mapped[T] | Mejor análisis estático, autocompletado |
💡 Tip: El método moderno es compatible con Flask-SQLAlchemy 3.x y ofrece mejor rendimiento y mantenibilidad a largo plazo.
Con SQLAlchemy, puedes conectar tus modelos como si fueran piezas de LEGO (pero sin el dolor de pisar una descalzo 😆). Ya sea 1:1 (como un celular y su dueño), 1:N (como un meme y sus mil compartidos), o N:M (como tus series favoritas y tus noches de insomnio), ¡el ORM te tiene cubierto!
¡Ahora ve y escribe queries como si el código se autodocumentara! 🦸♂️💻
(Y recuerda: si tu código funciona a la primera, es hora de sospechar... o de celebrar con un café ☕).
¿Listo para el siguiente nivel? ¡SQLAlchemy te espera! 😉