This is a short post to share my journey as I faced more challenges than usual learning some new tech.
Coming from a Django background, I recently started learning FastAPI and decided to try SQLAlchemy with it, as it’s the de facto ORM for this framework. Having heard many contrasting opinions about SQLAlchemy, I was curious to form my own.
Spoiler alert: I love SQLAlchemy—but not its documentation (at least, for learning it from scratch).
Let me take you through my challenging journey and its rewarding conclusion.
❌ First Attempt: FastAPI Official Tutorial
Naturally, I began learning SQLAlchemy alongside FastAPI by following its official tutorial. The author of FastAPI recommended using SQLModel as the preferred approach. To reinforce this, the older tutorial based on raw SQLAlchemy was removed, leaving me with no choice but to blindly follow the SQLModel tutorial and see where it would lead me. At the time, I thought SQLModel was the next big thing—an improved way to work with FastAPI.
Without diving into too many details, the main issue with SQLModel is that it adds an abstraction layer on top of both SQLAlchemy and Pydantic (a data validation library). While these abstractions may be helpful in the long run, they make it incredibly challenging for a beginner to understand why things behave the way they do or to distinguish between features belonging to SQLAlchemy and Pydantic. In short, while these abstractions might simplify things eventually, they make learning the core concepts an absolute headache.
As I began questioning my approach, I turned to Reddit for advice. I found that many people shared my concerns and strongly advised me against using SQLModel altogether. Encouraged by this, I migrated my small training project to raw SQLAlchemy, relying on ChatGPT for assistance. However, even after the migration, I still felt far from proficient with SQLAlchemy.
❌ Second Attempt: YouTube Video
Next, I thought, why not try a free YouTube tutorial? This one seemed promising, so I decided to give it a shot. The video had excellent reviews, and I soon realized it was recorded by the creator of SQLAlchemy himself. Perfect, right?
Well… not exactly. I quickly noticed some red flags that often appear when someone lacks strong teaching skills. For instance, the video made many assumptions about the viewer’s prior knowledge and struggled to strike the right balance between showing how to achieve a result and explaining how the entire system works. While both aspects are valuable, they shouldn’t be mixed in a way that overwhelms a beginner in an introductory tutorial. At this stage, abstract concepts that aren’t immediately necessary only add confusion.
In the end, I completed the video and learned a few things, but not as much as I had hoped.
❌ Third Attempt: Official documentation
In the video I just mentioned, the author recommended some must-read parts of documentation after this video, so I decided to check them out. Yet again, the same feeling returned: something was off. Why did the author insist on diving into the internals of everything when I didn’t have the cognitive capacity to handle it at this stage?
To make matters worse, the more interesting content seemed buried deep within the documentation. As I explored it, I was struck by how cryptic and overwhelming it felt. The documentation is likely an excellent reference for those already familiar with the framework, but it lacked the "hand-holding" approach I appreciate when learning something new.
To be honest, at that point, I started questioning myself: What am I doing wrong? Is SQLAlchemy really this hard? Or am I just too stupid to learn this ORM?
✅ Fourth Attempt: A Book (The big reveal)
In a desperate attempt, I turned to Amazon and came across this highly rated book: SQLAlchemy 2 In Practice, by Miguel Grindberg. Reading the reviews, I realized I wasn’t alone in struggling with the documentation and searching for a better way to learn this tool.
I decided to purchase the $10 Kindle version, and as soon as I started reading, I thought: “Oh, thank God! THIS is what teaching should look like.”
The book had the perfect level of verbosity for an intermediate developer. It made no assumptions about prior experience, willingly explained the basics of SQL and architectural concepts, and outlined decisions clearly. Everything was concise, clear, and straight to the point. The content was progressive—building a fictional project through small iterations, with each step introducing a new concept. The author clearly understood the limits of human cognitive load.
Each chapter ended with exercises to practice queries, which I found essential. Writing effective ORM queries doesn’t come as intuitively to me as Python code, so practicing was crucial to becoming comfortable with it.
The book’s fake projects were specifically designed to cover use cases that teach all the key concepts. To work through the exercises, I set up a development environment using VS Code Dev Containers and Jupyter notebooks, sothat I can come back later of I need to.
Conclusion
For me, one of the core aspects of any framework—especially in back-end development—is how it handles data. A corrupted database is one of the worst things that can happen in production, which is why I dedicate time to truly understand what I’m doing in this area. Learning efficiently is crucial.
I understand why some people might hesitate to buy a book for a beginner-level introduction to a technology. Personally, I’m not usually a fan of books for learning code, and the Kindle app is awful on macOS. But sometimes, the content matters more than the format.
I’m still in the process of learning, but now I feel much more confident. I’m grateful for people who have the gift of explaining things clearly and effectively. On the other hand, I think the creator of SQLAlchemy is probably a genius—but one who struggles to imagine how the average person’s brain works. But that’s fine :)