You define a clean GraphQL schema. Users have posts, posts have authors, and tags connect everything. Then you wire it up to your SQLAlchemy models and spend a few hours writing resolvers that basically re-describe relationships you've already modelled. Even worse, this approach frequently leads to the dreaded N+1 problem.
A query like that looks fine:
```graphql
{
posts {
title
author { username }
tags { name }
}
}
```
However, without the right loading strategies, it hits the database once for the post list, once per post for the author, and once per post for the tags. For ten posts, that is 21 queries. For a hundred, it jumps to 201. While your resolver code remains identical, the SQL log tells a different story.
The standard fix is a DataLoader, which batches the individual loads, fires one `WHERE id IN (...)` for the whole set. It works, but you still write one per relationship, by hand, every time.
We ran into this on every project we touched. At some point, we got tired of solving it from scratch.
GraphQL is a query language for APIs. You define a typed schema, expose it over a single endpoint, and clients request exactly the fields they need – specific columns, nested objects, or relationships – in a single request.
Underneath, your data model is a graph of connected domain objects. Clients query this graph like a tree: they pick a root field and declare what they want at each level, choosing exactly where to stop:
```graphql
{
posts {
title
author { username }
tags { name }
}
}
```
The runtime resolves this tree field by field, calling a specific resolver at each node. Each resolver returns either a scalar value or an object for the next layer. This depth-first traversal is also why database performance is easy to mismanage: each resolver operates independently, often without built-in coordination.
While graphql.org/learn is a great starting point for the basics, for a closer look at the evolution of these API standards and why GraphQL has become the preferred choice for modern, complex web applications, see our analysis of GraphQL.
There are two primary ways to build GraphQL APIs in Python: code-first or schema-first. Ariadne chooses the latter, meaning you write your SDL directly as the source of truth. This contract is explicit, readable, and serves as an ideal foundation for documentation generators, linters, and AI agents:
```graphql
type Query {
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: User!
}
```
This explicit nature is exactly why schema-first pays off when building resilient, AI-ready architectures.
Relational databases think in sets and JOINs. GraphQL traverses a nested tree, field by field. The two don't map cleanly, and that gap usually results in manual boilerplate code that you have to write and maintain yourself.
A resolver for `posts` without any integration looks something like this:
```python
@query.field("posts")
def resolve_posts(_, info):
session = info.context["session"]
return session.execute(
select(Post).options(
joinedload(Post.author),
selectinload(Post.tags),
)
).unique().scalars().all()
```
If you miss a joinedload, you get the N+1 problem. Add a relationship to your model, and you're hunting through resolvers to update them. To start using the new integration, simply run:
```bash
pip install ariadne[sqlalchemy]
```
The integration solves this through two complementary paths:
SQLAlchemyQueryType: Reads the GraphQL selection set before any resolver fires. It determines what the client asked for and builds one optimized SQL statement per root field, automatically applying selectinload or joinedload. For most fields, the manual .options() calls – and the resolvers themselves – simply disappear.SQLAlchemyObjectType: Acts as a safety net for custom resolvers. If you perform a query that bypasses the lookahead, this routes relationship lookups through a per-request DataLoader, ensuring everything is batched automatically without you writing the loader code.Register your models with the integration:
```python
from ariadne.contrib.sqlalchemy import SQLAlchemyObjectType, SQLAlchemyQueryType
user_type = SQLAlchemyObjectType("User", User)
post_type = SQLAlchemyObjectType("Post", Post)
tag_type = SQLAlchemyObjectType("Tag", Tag)
query_type = SQLAlchemyQueryType([user_type, post_type, tag_type])
schema = make_executable_schema(type_defs, [query_type, user_type, post_type, tag_type])
```
Then, add your session to the GraphQL context:
```python
async def get_context(request, _data):
return {"request": request, "session": request.state.session}
```
Now, a query like { posts { title author { username } tags { name } } } works automatically, issuing one efficient SQL statement instead of 21. You can find a complete, runnable example in our GitHub repository.
While the defaults are designed for most common scenarios, you can fine-tune behavior using SQLAlchemyObjectType arguments:
aliases): Map GraphQL camelCase fields to your snake_case SQLAlchemy attributes.strategies): Override the loading strategy (e.g., swapping in subqueryload) when defaults aren't optimal.max_depth): Set a limit (default is 3) to prevent runaway queries from hitting your database.```python
from sqlalchemy.orm import selectinload
post_type = SQLAlchemyObjectType(
"Post",
Post,
aliases={"authorId": "author_id"},
strategies={"author": selectinload},
max_depth=4,
)
```Not every query follows the "auto" path. A resolver that filters by a condition needs to run its own custom query:
```python
@query_type.field("publishedPosts")
def resolve_published_posts(_, info):
session = info.context["session"]
return session.execute(select(Post).where(Post.is_published)).scalars().unique().all()
```
Even though these objects bypass the lookahead, you can still batch relationship resolution by adding SQLAlchemyDataLoaderExtension to your HTTP handler:
```python
http_handler=GraphQLHTTPHandler(extensions=[SQLAlchemyDataLoaderExtension])
```
With this in place, the relationship lookups remain efficient. You can see this in action in our DataLoader fallback example.
This integration started as a pattern we kept solving on our own projects. At some point, it made sense to pull it out, clean it up, and share it. By open-sourcing it, we hope to provide a more scalable way to handle SQLAlchemy and GraphQL.
That's where open source gets interesting. We built for the problems we had. Other teams have different schemas, different scales, different needs - and that diversity is what shapes a library into something genuinely useful! That’s why we invite the community to explore the full documentation or check out the runnable examples on GitHub to see how it fits your specific use case.