What if the database layer of your next TypeScript app could feel less like magic and more like SQL you actually understand? That is the pitch behind Drizzle ORM, a thin, TypeScript-first toolkit that has quietly become one of the most talked-about ways to talk to PostgreSQL. Unlike heavyweight ORMs that hide SQL behind layers of abstraction, Drizzle hands you a schema written in plain TypeScript and a query builder that reads almost like the SQL it produces. For developers tired of generated clients and opaque error messages, that is a refreshing change. (TypeScript)
This tutorial walks through the practical path: installing Drizzle, defining a PostgreSQL schema, running migrations with drizzle-kit, and querying data with full type safety. It also covers the mistakes that trip up newcomers and how Drizzle compares to the ORM many teams already use. Whether you are building a side project or refactoring a production API, the goal here is a working mental model, not a pile of copy-paste snippets.
Why Drizzle Fits TypeScript Projects So Well
The core idea is simple. You describe your tables using functions imported from `drizzle-orm/pg-core`, and TypeScript infers row types directly from that schema. There is no separate schema language and no code-generation step that produces a giant client. According to the Drizzle documentation, the library is designed to be “SQL-like” and to stay close to the underlying database, which is exactly why teams migrating from raw queries find it approachable. (TypeScript Documentation)
That design has real consequences. When a query fails, the error usually points at your SQL, not at an abstraction layer. When you need a window function or a lateral join, you can often express it directly. And because the schema lives in TypeScript, your editor autocompletes column names and catches typos before runtime. The trade-off is that Drizzle assumes you are comfortable with relational thinking. If you have never written a `JOIN`, this is a good excuse to learn.
Setting Up Drizzle With PostgreSQL
Before writing any schema, you need a PostgreSQL database and a TypeScript project. The setup below follows the general flow described in the official PostgreSQL getting-started guide, though package names and config keys can shift between releases, so always cross-check against the current docs.
Start by installing the runtime packages and the CLI:
- Install `drizzle-orm` plus a driver such as `pg` (node-postgres) or `postgres` (postgres-js).
- Install `drizzle-kit` as a development dependency.
- Create a `drizzle.config.ts` file at the project root.
- Point the config at your schema file and set the dialect to `postgresql`.
- Store your connection string in an environment variable, never in source code.
The config file is where drizzle-kit learns where your schema lives, where to write migration files, and how to reach the database. A typical setup declares a `schema` path, an `out` directory for migrations, `dialect: ‘postgresql’`, and a `dbCredentials` object that reads from `process.env.DATABASE_URL`. Getting this file right early saves hours later, because every migration command depends on it.
A common beginner mistake is committing the `.env` file or hardcoding credentials into the config. Another is forgetting that drizzle-kit needs its own path to the database, separate from whatever connection your application code uses at runtime. Treat those as two distinct concerns: one for migrations, one for queries.
Schema declaration is where Drizzle shines. You import table and column helpers from `drizzle-orm/pg-core` and describe each table as a plain object. A `users` table might use `serial` for an auto-incrementing primary key, `text` for names, and `timestamp` for audit fields. Foreign keys are expressed with `.references()`, and indexes are declared alongside the columns they cover.
The payoff arrives with type inference. Drizzle exposes helpers like `typeof users.$inferSelect` and `typeof users.$inferInsert`, which derive the shape of a selected row and an insertable row respectively. That means your application code can type a function parameter as the inferred select type and stay in sync automatically whenever the schema changes. The type inference documentation explains this pattern in detail, and it is worth reading before you start hand-writing interfaces that duplicate what the schema already knows.
Two practical tips from experience. First, name your columns explicitly in snake_case while keeping camelCase in TypeScript, so the database stays conventional and your code stays idiomatic. Second, define relations early if you plan to use the relational query API, because those relation definitions power the nested query helpers later.
Running Migrations With drizzle-kit
Migrations are the part most tutorials gloss over, and they are also where real projects break. Drizzle offers a few commands with distinct jobs. `drizzle-kit generate` compares your TypeScript schema against the previous snapshot and writes a SQL migration file. `drizzle-kit migrate` applies pending migration files to the database. `drizzle-kit push` skips the files entirely and pushes the schema straight to the database, which is convenient for prototyping but risky in production because you lose the reviewable history.
| Command | What it does | Best for |
|---|---|---|
| `generate` | Creates SQL migration files from schema diffs | Teams that review changes |
| `migrate` | Applies pending migration files | Staging and production |
| `push` | Syncs schema directly, no files | Local prototyping only |
| `studio` | Opens a browser-based data browser | Inspecting rows quickly |
The workflow that holds up over time is straightforward: change the schema, run `generate`, read the generated SQL carefully, commit it, then run `migrate` in each environment. Reading the SQL matters. A seemingly innocent column rename can produce a drop-and-add pair that silently destroys data, and only a human reviewing the file will catch it. The migrations guide covers the folder structure and journal file that track which migrations have run.
Querying Data With the SQL-Like Builder
Once the schema and migrations are in place, querying feels familiar. The core API offers `select`, `insert`, `update`, and `delete` functions that chain together. A basic read looks like `db.select().from(users).where(eq(users.id, 1))`, where `eq` comes from the `drizzle-orm` package. Joins, ordering, limits, and aggregates all follow the same shape, and the generated SQL is predictable enough that you can reason about performance without guessing.
For nested data, Drizzle provides a relational query API. When relations are defined in the schema, you can call `db.query.users.findMany()` with a `with` clause to pull related rows in one call. The relational query docs explain how this maps to SQL under the hood. It is genuinely convenient, but it is not magic: complex filters still benefit from the core builder, and mixing both styles in one codebase is normal.
A frequent gotcha is forgetting that Drizzle does not add a `LIMIT` for you. Another is assuming `select()` returns a plain object when you have used a join, which can produce nested result shapes. Log the generated SQL during development using the `logger` option, and these surprises disappear fast.
Connecting Drizzle to an Application
The database client itself is created once per process. With node-postgres, you import `drizzle` from `drizzle-orm/node-postgres`, create a pool, and pass it in along with your schema. In serverless environments, connection pooling becomes the hard part, and that is where teams often reach for a pooled connection string or a driver built for edge runtimes.
It is worth stepping back to see how this fits the wider stack. Modern TypeScript apps juggle several moving parts at once, from database layers to platform decisions. The same week you wire up Drizzle, you might also be reading about Apple’s 27 percent App Store fee battle or weighing Tesla’s robotaxi, Semi, and Roadster hardware bets. None of that changes your schema, but it is a reminder that the database is one piece of a much larger product puzzle.
For teams building developer tooling or game backends, the choice of data layer also shapes tooling choices elsewhere. Studios comparing Roblox Studio, Unity, and Godot often end up with a TypeScript service on the side, and Drizzle slots neatly into that role. The point is consistency: pick a data layer you can reason about, then let the rest of the stack follow.
Drizzle Versus Prisma: A Fair Comparison
Most developers arrive at Drizzle after using Prisma, so the comparison is inevitable. Prisma uses its own schema language, generates a client, and historically shipped a query engine binary. Drizzle keeps everything in TypeScript and leans on SQL. Neither is universally better; the right pick depends on team skills and project constraints.
| Factor | Drizzle | Prisma |
|---|---|---|
| Schema location | TypeScript files | Separate `.prisma` schema |
| Query style | SQL-like builder | Fluent client API |
| Generated client | No separate engine | Generated client |
| Learning curve | Steeper for SQL newcomers | Gentler for beginners |
| SQL control | Very high | Moderate |
Benchmark claims float around both libraries, and most are unreliable without a dated, reproducible test. The honest answer is that for typical CRUD workloads, the difference is small compared to query design and indexing. Choose Drizzle if your team thinks in SQL and wants transparency. Choose Prisma if you want a guided, batteries-included experience and do not mind the extra abstraction.
Mistakes That Cost Beginners Time
Some pitfalls show up again and again in Drizzle projects, and knowing them in advance is half the battle. None of these are exotic; they are the ordinary friction of learning a new tool.
- Skipping the schema review before running `push` against a shared database.
- Forgetting to regenerate types after a schema change, then wondering why the editor complains.
- Writing raw SQL strings when the query builder already supports the operation.
- Ignoring connection pool limits in serverless functions, which produces timeouts under load.
- Defining relations late, after queries are already written, forcing a refactor.
- Assuming the ORM handles transactions automatically across multiple calls.
The fix for most of these is discipline rather than cleverness: review migrations, keep one source of truth for the schema, and test against a real PostgreSQL instance rather than a mock.
Conclusion
Drizzle ORM rewards developers who are willing to think in SQL. The setup is light, the schema is plain TypeScript, and the type inference means fewer hand-written interfaces and fewer runtime surprises. Migrations through drizzle-kit give you a reviewable history if you resist the temptation to `push` everywhere, and the query builder stays close enough to the metal that performance problems are diagnosable rather than mysterious. It is not the easiest ORM to start with, but for teams that value transparency and control, it is a strong fit. Start small, review your generated SQL, and let the schema do the typing work for you.
Frequently Asked Questions
Is Drizzle ORM good for beginners?
It depends on the beginner. If you already understand basic SQL concepts like joins and foreign keys, Drizzle is approachable and teaches good habits. If you have never written a query, a more guided ORM may be gentler at first, and you can move to Drizzle later once the relational model clicks.
Do I need drizzle-kit to use Drizzle ORM?
Not strictly, but you will want it. drizzle-kit handles migration generation and schema syncing, which are essential for any project that changes over time. Without it, you would be writing and applying SQL migrations by hand, which works but loses the convenience of automated diffs.
Can Drizzle work with databases other than PostgreSQL?
Yes. Drizzle supports several SQL dialects, including MySQL and SQLite, through separate import paths. The core concepts stay the same, but column helpers and driver adapters differ by dialect, so check the docs for your specific database before copying a PostgreSQL example.
How does Drizzle handle type safety?
Types are inferred directly from your TypeScript schema. Helpers like the select and insert inference utilities derive row shapes automatically, so changing a column updates the types everywhere they are used. This removes the need to maintain duplicate interfaces by hand.
Should I use push or migrations in production?
Use migrations in production. The `push` command skips reviewable SQL files and applies changes directly, which is fine for local prototyping but dangerous on shared databases. Generated migration files can be reviewed, committed, and replayed consistently across environments.
Is Drizzle faster than Prisma?
Performance comparisons are noisy and depend heavily on the query and workload. For most CRUD applications, the difference is minor compared to indexing and query design. Drizzle’s thinner layer may reduce overhead in some cases, but claims of a large speed gap should be treated with skepticism unless backed by reproducible benchmarks.
