SQLAlchemy es una librería de Python para trabajar con bases de datos relacionales desde el código. Incluye un ORM, que convierte tablas en clases y filas en objetos, y un Core para construir consultas SQL con Python. Funciona con PostgreSQL, MySQL, MariaDB, SQLite, Oracle y SQL Server y se instala con pip install sqlalchemy.
Trabajar con bases de datos es una de las competencias más importantes para cualquier desarrollador backend, analista de datos o ingeniero Python. Y dentro del ecosistema Python, pocas herramientas han tenido tanto impacto como SQLAlchemy, la librería más potente y flexible para interactuar con bases de datos SQL.
Aunque su nombre pueda intimidar al principio, SQLAlchemy no está pensado solo para expertos. De hecho, es una herramienta diseñada para ayudarte a trabajar con bases de datos de forma más limpia, eficiente y mantenible, sin necesidad de escribir SQL manual en cada operación… a menos que quieras hacerlo.
SQLAlchemy combina lo mejor de dos mundos:
Un ORM completo, que te permite trabajar con datos como objetos de Python.
Un Core SQL muy potente, para quienes prefieren escribir consultas SQL optimizadas.
Gracias a esto, es utilizado en proyectos pequeños, aplicaciones web en producción, APIs modernas (FastAPI, Flask), sistemas de análisis de datos y hasta en entornos empresariales.
En esta guía aprenderás qué es SQLAlchemy, cómo funciona, para qué sirve, qué ventajas ofrece y cómo empezar a usarlo con ejemplos de código al estilo de SQLAlchemy 2.x, el que enseña hoy la documentación oficial.
¿Qué es SQLAlchemy?
SQLAlchemy es una librería de Python para trabajar con bases de datos SQL de forma flexible, eficiente y escalable. A diferencia de otras herramientas, SQLAlchemy no es solo un ORM: es un ecosistema completo que incluye dos formas de interactuar con bases de datos:
1. SQLAlchemy ORM (Object Relational Mapper)
Es la parte más conocida de la librería.
Permite mapear tablas y filas a clases y objetos de Python, de manera que puedes trabajar con datos usando atributos y métodos en lugar de consultas SQL manuales.
Ejemplo simple con ORM:
Con el ORM:
✔ Escribes menos SQL
✔ Reduces errores
✔ El código es más legible
✔ Es ideal para aplicaciones completas (APIs, microservicios, dashboards)
2. SQLAlchemy Core (SQL puro pero mejorado)
Es una capa que permite escribir consultas SQL de forma estructurada, manteniendo control total sobre la base de datos.
Perfecto para:
Consultas complejas
Optimización avanzada
ETLs o pipelines de datos
Proyectos donde necesitas SQL explícito
Ejemplo Core:
¿Por qué SQLAlchemy es tan popular?
SQLAlchemy funciona con casi todos los motores de base de datos SQL, incluyendo:
SQLite
MySQL
PostgreSQL
MariaDB
Oracle
SQL Server
Además, se integra perfectamente con frameworks modernos como FastAPI, Flask, Django (como alternativa al ORM nativo) y entornos de análisis de datos.
Ventajas clave:
Super robusto y maduro
Gran comunidad
Altamente configurable
Código limpio y mantenible
Control total sobre el SQL cuando hace falta
ORM industrial, no solo educativo
Se usa en APIs con FastAPI y Flask
Por eso se utiliza tanto en proyectos profesionales, desde startups hasta plataformas empresariales.
¿Qué es un ORM y por qué usarlo?
Un ORM (Object-Relational Mapper) es una herramienta que permite trabajar con bases de datos SQL utilizando clases y objetos de Python en vez de escribir consultas SQL manuales. En otras palabras, convierte las tablas, filas y columnas en estructuras de Python que puedes manipular como cualquier otro objeto del lenguaje.
Esto facilita muchísimo el trabajo con datos en aplicaciones reales, especialmente cuando la lógica del proyecto crece o cuando necesitas mantener el código durante meses o años.
¿Cómo funciona un ORM en la práctica?
Imagina que tienes una tabla users con columnas id, name y email.
Con SQL, tendrías que escribir esto:
Pero con ORM, simplemente haces:
La consulta sigue siendo SQL por dentro, pero tú trabajas con objetos Python.
El resultado: un código más legible, mantenible y fácil de depurar.
¿Qué mapea un ORM dentro de la base de datos?
Tablas → Clases Python
Filas → Objetos (instancias)
Columnas → Atributos
Claves ajenas → Relaciones entre objetos
Ejemplo mínimo de mapeo:
Aquí User representa a la tabla users, y cada fila será una instancia del objeto.
¿Por qué usar un ORM? Beneficios reales
Los ORMs no existen por comodidad: resuelven problemas reales en desarrollo profesional.
1. Código más limpio y más fácil de mantener
Trabajas con Python puro en vez de mezclar SQL dentro de tu negocio.
2. Menos errores
Menos SQL repetido o mal formateado. Tipos, claves y relaciones se declaran una vez en el modelo, en lugar de repetirse en cada consulta.
3. Independencia del motor de base de datos
Pasar de SQLite a PostgreSQL suele exigir cambiar poco más que la URL de conexión y el driver, aunque las particularidades de cada motor pueden pedir ajustes.
4. Mayor productividad
Menos líneas de SQL, menos boilerplate, más foco en la lógica de tu aplicación.
5. Seguridad mejorada
El ORM envía los valores como parámetros y no pegados al texto SQL, lo que evita la inyección SQL. Si escribes SQL a mano con text(), usa parámetros con nombre (:id) y no concatenes texto: la documentación oficial pasa los valores aparte, en un diccionario. Más en cómo evitar ataques de SQL injection.
6. Se integra perfecto con APIs modernas
SQLAlchemy se usa con FastAPI y Flask. El tutorial oficial de FastAPI usa SQLModel, una librería construida sobre SQLAlchemy y Pydantic (FastAPI, consultado el 23 de octubre de 2026). Para más contexto, qué es una API RESTful.
¿Por qué SQLAlchemy tiene uno de los mejores ORMs?
A diferencia de otros ORMs simplificados, el de SQLAlchemy:
Tiene calidad industrial
Soporta relaciones complejas
Permite optimizaciones avanzadas
No te encierra: siempre puedes mezclar ORM con SQL puro
Funciona con cualquier tipo de arquitectura (microservicios, APIs, ETLs)
¿Para qué sirve SQLAlchemy?
Durante los últimos años SQLAlchemy se ha convertido en una herramienta potente para los programadores, porque hace que el acceso a las bases de datos SQL por medio de Python sean mucho más sencillos.
Además, es una librería bastante completa y compuesta por una serie de herramientas que hacen posible la creación, gestión y consultas en bases de datos variadas. Todo esto de manera sencilla, eficiente y, sobre todo, segura.
Por supuesto, puedes valerte de su ORM para no tener que escribir de manera directa los comandos de SQL, pero cuando lo necesites la librería te permitirá hacerlo sin problema.
Es así como esta biblioteca les permite tener a todos sus usuarios un control completo en la interacción con la base de datos en todo momento.
¿SQLAlchemy Core o ORM? Cómo elegir
Usa el ORM cuando tu aplicación gira en torno a entidades con relaciones (usuarios, pedidos, cursos) y Core cuando necesitas consultas cercanas al SQL, como informes o cargas masivas. No hay que elegir una vez y para siempre: ambos comparten el mismo select() y puedes mezclarlos en el mismo proyecto (tutorial oficial).
ORM: altas, bajas y modificaciones de objetos, relaciones entre tablas, APIs y aplicaciones web.
Core: informes, ETL, consultas con muchos
JOINy casos donde quieres ver y controlar el SQL exacto.SQL a mano con
text(): consultas muy específicas del motor. Pasa siempre los valores como parámetros.
Una regla práctica: empieza con el ORM y baja a Core solo en la consulta que lo necesite.
Las funcionalidades principales de SQLAchemy
Tras comprender las definiciones básicas sobre la librería y su modo de trabajar, es momento de establecer cuáles son las funciones principales que presenta SQLAlchemy y los motivos por los cuales tantos desarrolladores la eligen para gestionar sus bases de datos.
Dicha librería de Python sorprende por lo completa que es y por poseer todas estas funcionalidades dentro de un mismo espacio:
Un ORM potente
Por supuesto, su poderoso ORM es la principal función a destacar, ya que tiene una potencia de nivel industrial.
El mismo se encuentra construido desde el mero núcleo del mapa de identidad y desde los patrones del mapeador de datos. Es a través de dichos patrones que es posible que todas las tareas realizadas con los objetos se mantienen transparentes a lo largo del tiempo.
Esta librería te permitirá crear modelos de dominio desde cero y gestionarlos según lo que necesites en cada momento.
Por lo tanto, es gracias a su ORM que se vuelve posible mapear las clases en la base de datos y simplificar todo lo que tiene que ver con el control y la gestión de los datos almacenados.
Soporte para distintas bases de datos
SQLAlchemy también es reconocida por ser una librería que tiene soporte para bases de datos muy variadas. Por lo tanto, no importa con cuál trabajes, es bastante probable que puedas gestionarla por medio de esta biblioteca.
Entre su amplia gama de opciones, te será posible gestionar bases de datos PostgreSQL, MySQL, MariaDB, SQLite, Oracle y SQL Server, los motores con dialecto incluido en la documentación oficial.
Lenguaje de consulta expresivo
La biblioteca también cuenta con un Expressive Query Language (lenguaje de consulta expresivo) con el cual se pueden realizar las consultas de manera rápida e intuitiva, sencilla de entender incluso para los novatos.
Todo su sistema de consultados está centrado en ofrecer un acceso sencillo a todas las capacidades de la base de datos, desde las correlaciones, hasta las combinaciones.
Asimismo, las consultas que realices con el ORM se fundamentan sobre la misma composición relacional que se emplea al escribir el SQL, por lo que resulta de fácil entendimiento para los desarrolladores.
Gestión de transacciones
Se conoce como transacciones a las secuencias de operaciones que se realizan sobre una base de datos. Por medio de SQLAlchemy es posible agrupar las operaciones en transacciones de manera consistente.
Por supuesto, para llevar a cabo una buena gestión con las transacciones, es importante que todas las operaciones se hayan efectuado de forma correcta. En caso de que una operación falle, la transacción también lo hará.
Migraciones con Alembic
Para terminar, una aclaración: SQLAlchemy no incluye una interfaz gráfica de administración. Lo que sí existe en su ecosistema es Alembic, una herramienta ligera de migraciones de base de datos para usar con SQLAlchemy.
Con Alembic versionas los cambios en la estructura de tu base de datos (tablas nuevas, columnas añadidas) en vez de modificarla a mano, de modo que todo el equipo y todos los entornos aplican los mismos cambios en el mismo orden.

Si quieres aprender a construir aplicaciones completas con base de datos, el programa Rock the AI Code te propone «Aprende full stack development con IA» con acceso durante 18 meses a la plataforma: descarga el dossier de Rock the AI Code.
¿Cómo instalar SQLAlchemy?
Instalar SQLAlchemy es rápido y sencillo, y puedes hacerlo utilizando PIP o Conda, según el entorno que estés usando para tus proyectos. Aquí tienes los métodos recomendados paso a paso.
Instalación con PIP (la opción más común)
Si trabajas con entornos virtuales de Python (venv, virtualenv, o poetry), esta es la opción ideal.
Abre tu terminal o CMD.
Ejecuta:
Para verificar que todo se instaló correctamente:
Verás información como versión, ruta de instalación y dependencias.
¿Qué versión de SQLAlchemy se instala hoy?
Con pip install sqlalchemy se instala la última versión publicada. A 23 de octubre de 2026 es SQLAlchemy 2.1.6 (21 de octubre de 2026); la serie 2.0 sigue en mantenimiento (2.0.55, del 16 de octubre) y la 1.4 está fuera de soporte (sqlalchemy.org). Si usas la versión asíncrona, instala pip install sqlalchemy[asyncio]: en 2.1, greenlet ya no se instala por defecto.
Instalación con Conda (ideal si usas Anaconda o Miniconda)
Si ya trabajas con entornos administrados por Conda, sigue estos pasos:
Abre Anaconda Prompt o tu terminal.
Ejecuta:
Conda te mostrará las dependencias antes de instalarlas. Confirma con y.
Para comprobar la instalación:
Recomendación profesional: usa un entorno virtual
SQLAlchemy suele instalarse junto a otros paquetes (FastAPI, Alembic, SQL drivers...). Por eso lo mejor es crear un entorno dedicado al proyecto:
Controladores opcionales que puedes necesitar
SQLAlchemy no incluye los drivers de bases de datos. Para conectar con cada motor, deberías instalar:
Base de datos | Driver recomendado | Instalación |
|---|---|---|
PostgreSQL |
|
|
MySQL |
|
|
SQLite | Ya viene incluido en Python | ❌ No requiere instalación |
SQL Server |
|
|
Esto mejora la compatibilidad y el rendimiento de tus proyectos.
¿SQLAlchemy funciona en cualquier sistema operativo?
Sí. Funciona perfectamente en Windows, macOS y Linux, siempre que tengas una versión de Python compatible. SQLAlchemy 2.1 exige Python 3.11 o superior (documentación, versión 2.1) y la serie 2.0 admite Python 3.7 o superior. Python 3.8 está fuera de soporte desde octubre de 2024 y Python 3.10, desde octubre de 2026 (Python Developer's Guide).
¿Cómo comenzar a trabajar con SQLAlchemy?
Si ya has instalado SQLAlchemy en tu ordenador y quieres comenzar a gestionar tu base de datos con esta librería, es momento de dar los primeros pasos y, para la mayoría de los usuarios, son los más complicados.
Es por ello que, a continuación, te explicaremos lo que debes hacer para sacarle provecho a esta librería.
1. Importar SQLAlchemy
Lo primero es importar los módulos esenciales.
DeclarativeBase es la clase de la que heredará la base de tus modelos, las clases que representan tablas en tu base de datos. Mapped y mapped_column() declaran cada columna con su tipo de Python. declarative_base() sigue disponible, pero es la forma anterior de crear esa base.
2. Crear el motor de base de datos (engine)
El engine es la conexión entre Python y el motor SQL.
Por ejemplo, para conectarte a SQLite:
Si usas PostgreSQL:
El parámetro echo=True muestra en consola el SQL que ejecuta SQLAlchemy (perfecto para aprender).
3. Definir los modelos de datos
Los modelos son clases de Python que representan tablas SQL.
Aquí es donde SQLAlchemy ORM empieza a brillar:
✔ Cada atributo = una columna
✔ Cada instancia = una fila en la tabla
✔ Fácil de leer, mantener y expandir
4. Crear las tablas en la base de datos
Una vez definidos los modelos:
Instantáneamente tendrás las tablas creadas sin escribir SQL manual.
5. Crear una sesión (la capa que gestiona transacciones)
La sesión es la herramienta que te permite:
Insertar registros
Actualizar valores
Ejecutar consultas
Confirmar o revertir transacciones
En un script corto basta con eso, pero cierra la sesión al terminar. En aplicaciones, lo recomendado es usarla como gestor de contexto (with Session(engine) as session:), que la cierra al salir del bloque, o crear un sessionmaker(engine) una sola vez junto al engine (documentación de la Session). Solo hace falta commit() cuando escribes datos.
6. Insertar datos
Ejemplo básico: crear un usuario.
7. Consultar datos
Ejemplo de consulta sencilla:
Consulta filtrada:
Esta es la forma 2.0 de consultar: construyes una sentencia con select() y la ejecutas desde la sesión. session.query() sigue funcionando, pero la documentación lo trata como API heredada (guía de migración a 2.0).
8. Actualizar un dato
9. Borrar un registro

SQLAlchemy 2.x frente al estilo antiguo: qué ha cambiado
En SQLAlchemy 2.x los modelos se escriben con DeclarativeBase y Mapped, y las consultas con select() ejecutado desde la Session. El estilo anterior (declarative_base(), Column y session.query()) sigue funcionando, pero la documentación oficial ya solo enseña el nuevo.
Si encuentras código antiguo en un tutorial o en un proyecto heredado, así se traduce:
Base:
Base = declarative_base()pasa aclass Base(DeclarativeBase): pass.Columnas:
id = Column(Integer, primary_key=True)pasa aid: Mapped[int] = mapped_column(primary_key=True).Consultas:
session.query(User).filter_by(name="Ana").all()pasa asession.scalars(select(User).where(User.name == "Ana")).all().Buscar por clave:
session.query(User).get(1)pasa asession.get(User, 1), que es el reemplazo recomendado.Sesión:
Session()abierta y sin cerrar pasa awith Session(engine) as session:.
El tipado es la ganancia más práctica: al declarar Mapped[int] o Mapped[Optional[str]], tu editor y las herramientas de verificación de tipos saben qué es cada atributo. La documentación presenta este estilo como compatible con PEP 484 (ORM Quick Start).
Errores comunes al empezar
Olvidar el
commit(): sin él, los cambios no se confirman. Conwith session.begin():se confirman solos si no hay error y se revierten si lo hay.Leer un objeto tras el
commit()y sorprenderse: por defecto, el commit marca los objetos como caducados y sus atributos se vuelven a cargar de la base de datos al leerlos (opciónexpire_on_commit).Concatenar valores en un SQL escrito a mano: usa parámetros con nombre y deja que SQLAlchemy los envíe aparte.
Ojo con las versiones: SQLAlchemy 2.1 exige Python 3.11 o superior, y la serie 2.0 sigue en mantenimiento. Si usas asistentes de código, contrasta lo que generan con la documentación de tu versión: según la Stack Overflow Developer Survey 2026, los asistentes y agentes de código son ya el caso de uso dominante de la IA entre los desarrolladores, y la confianza es mayor cuando pueden validar la respuesta con facilidad.
Con 2 o 3 horas a la semana de forma constante es suficiente para seguir el programa sin quedarte atrás, según la ficha de Rock the AI Code, que incluye 40 horas de contenido teórico y 80 guías de documentación técnica descargables: descarga el dossier de Rock the AI Code.
Para concluir
SQLAlchemy es una de las herramientas más potentes del ecosistema Python para trabajar con bases de datos SQL de forma rápida, eficiente y segura. Tanto si estás dando tus primeros pasos en programación como si ya construyes APIs, aplicaciones backend o pipelines de datos, dominar esta librería te abrirá puertas a proyectos más robustos y profesionales.
Su combinación de ORM + SQL Core, su compatibilidad con múltiples motores y su curva de aprendizaje razonable lo convierten en un estándar en desarrollo moderno. Aprender SQLAlchemy no solo te permite gestionar bases de datos sin complicaciones: te prepara para trabajar como desarrollador Python en entornos reales, creando aplicaciones escalables que cumplen requisitos de industria.
Y si quieres llevar tus habilidades al siguiente nivel, en ThePower Tech School encontrarás formaciones prácticas en Full Stack Development, Data Analytics y Power BI, donde trabajarás con bases de datos, APIs, SQL y herramientas profesionales desde los primeros módulos.
¿Listo para dominar tus datos con SQLAlchemy? Déjanos tus dudas en los comentarios y seguimos avanzando contigo.
FAQs – Preguntas frecuentes sobre SQLAlchemy
1. ¿SQLAlchemy es mejor que usar SQL puro?
Depende del proyecto.
SQLAlchemy ORM acelera el desarrollo y reduce errores; SQL Core te permite controlar consultas complejas. Lo ideal es combinar ambos según la necesidad.
2. ¿Necesito saber SQL para usar SQLAlchemy?
Para tareas básicas puedes trabajar solo con el ORM, pero para proyectos reales siempre es recomendable saber SQL. SQLAlchemy no sustituye SQL: lo complementa.
3. ¿Puedo usar SQLAlchemy con FastAPI o Flask?
Sí. SQLAlchemy se usa con FastAPI y con Flask, y Alembic se encarga de las migraciones. FastAPI no obliga a usar ninguna librería de datos: su tutorial usa SQLModel, que está construido sobre SQLAlchemy. Más opciones en desarrollo con Python: aplicaciones y frameworks.
4. ¿SQLAlchemy es adecuado para proyectos grandes?
Sí. SQLAlchemy está diseñado para aplicaciones escalables, microservicios y entornos con alto volumen de datos.
5. ¿SQLAlchemy sirve para Data Science?
Sí, especialmente para integrar Python con bases SQL en procesos ETL, análisis, dashboards o automatización de consultas.
6. ¿Cuál es la curva de aprendizaje?
Si ya sabes Python y SQL, lo básico (engine, modelos, sesión y consultas) se aprende antes que lo avanzado (relaciones, carga de datos, migraciones). Si no conoces SQL, empieza por ahí: entender lo que genera el ORM es parte del aprendizaje.
7. ¿Es compatible con MySQL, PostgreSQL y SQL Server?
Sí. Solo necesitas instalar el driver adecuado. SQLAlchemy es una de las librerías con mayor compatibilidad en el ecosistema Python.
8. ¿Qué diferencia a SQLAlchemy de Django ORM?
Django ORM viene integrado en Django y está pensado para ese framework; SQLAlchemy es independiente del framework y separa Core y ORM, así que puedes usarlo en Flask, FastAPI, scripts o pipelines de datos. Si tu proyecto es Django, lo habitual es quedarte con su ORM.
9. ¿Qué es SQLAlchemy?
SQLAlchemy es una librería de Python para trabajar con bases de datos relacionales. Tiene dos partes: un ORM, que representa tablas como clases y filas como objetos, y un Core, que construye consultas SQL con código Python. Funciona con PostgreSQL, MySQL, MariaDB, SQLite, Oracle y SQL Server.
10. ¿Qué es SQLAlchemy en Python y para qué sirve?
En Python, SQLAlchemy sirve para conectarte a una base de datos SQL, definir tablas como clases, insertar, consultar, actualizar y borrar datos y controlar las transacciones sin escribir cada sentencia a mano. Si lo necesitas, también puedes ejecutar SQL propio con text() dentro del mismo proyecto.
11. ¿Cómo instalar SQLAlchemy con pip?
Con el comando pip install sqlalchemy, mejor dentro de un entorno virtual. Después, pip show sqlalchemy te confirma la versión instalada. Para conectar con PostgreSQL, MySQL o SQL Server necesitas además el driver de cada motor, porque SQLAlchemy no lo incluye.
12. ¿Cómo instalar SQLAlchemy con conda?
Con conda install -c conda-forge sqlalchemy desde Anaconda Prompt o tu terminal. Conda muestra las dependencias antes de instalar y pide confirmación. Comprueba el resultado con conda list sqlalchemy. Los drivers de cada base de datos se instalan aparte.
13. ¿Qué es un ORM para Python?
Un ORM para Python es una librería que traduce las tablas de una base de datos a clases y las filas a objetos, de modo que consultas y modificas datos con código Python en lugar de SQL manual. SQLAlchemy es el más conocido, y Django trae el suyo integrado.
14. ¿Qué versión de SQLAlchemy debo usar?
Para proyectos nuevos, la última: a 23 de octubre de 2026 es la 2.1.6, que exige Python 3.11 o superior. La serie 2.0 sigue en mantenimiento. En ambas, escribe con select(), Session y Mapped, el estilo que muestra la documentación oficial.







