# better-drizzle

> Minimal, type-safe repository helpers for Drizzle ORM. Keep the type-safety, drop the repetitive query glue. better-drizzle wraps an existing Drizzle client and gives every table a small, consistent API for reads, writes, pagination, nested filters, relation loading, hooks, and plugins — without hiding Drizzle or rebuilding a full ORM.

better-drizzle is a thin repository-style wrapper (~7 KB) on top of Drizzle ORM. It does not replace raw Drizzle — you still define your schema, choose your driver, and reach for raw SQL whenever you want. It simply removes the query glue you would otherwise rewrite in every service.

Key characteristics:
- Not a new ORM. Does not hide Drizzle or rebuild a query engine.
- Supports PostgreSQL, MySQL, and SQLite through Drizzle's driver layer.
- Native-first batch operations: `upsertMany`, `updateEach`, `createMany`.
- Plugin system with lifecycle hooks, transforms, and model/client extensions.
- Transaction support with savepoints, retries, and lifecycle callbacks.
- Raw SQL passthrough with safety gates and dialect awareness.
- Scoped metadata via `$withContext()` for multi-tenancy and request tracing.
- Peer dependencies: `drizzle-orm` (>=0.30.0) and `typescript`.

## Documentation

- [Introduction](https://better-drizzle.com/docs): Overview of better-drizzle — what it is, what it does, and how it fits alongside Drizzle ORM.
- [Getting Started](https://better-drizzle.com/docs/getting-started): Install, configure, and run your first better-drizzle client in minutes.
- [Comparison with Raw Drizzle](https://better-drizzle.com/docs/comparison): Side-by-side comparison showing the query glue better-drizzle removes and the overhead it adds.

## Querying

- [Reads](https://better-drizzle.com/docs/querying/reads): findMany, findFirst, findOne, findUnique, count, and exists — the full read surface.
- [Filters](https://better-drizzle.com/docs/querying/filters): Typed where clauses with AND/OR/NOT, scalar operators, and nested relation filters.
- [Selecting Fields](https://better-drizzle.com/docs/querying/selecting-fields): Pick specific columns or load nested relations with select and include.
- [Relations](https://better-drizzle.com/docs/querying/relations): Loading related records — one-to-one, one-to-many, and many-to-many patterns.
- [Pagination](https://better-drizzle.com/docs/querying/pagination): `paginate()` for offset pages and `cursor()` for cursor navigation, both with typed metadata.

## Writing

- [Create, Update & Delete](https://better-drizzle.com/docs/writing/crud): The full write surface — create, createMany, update, updateMany, updateEach, delete, deleteMany, upsert, and upsertMany.
- [Throwing Results](https://better-drizzle.com/docs/writing/throwing-results): Use .throw() on nullable results to convert null into a typed error instead of manual null checks.

## Advanced

- [Transactions](https://better-drizzle.com/docs/advanced/transactions): Transaction API with savepoints, retries, timeouts, AbortSignal support, and lifecycle hooks.
- [Hooks](https://better-drizzle.com/docs/advanced/hooks): beforeCreate, afterQuery, onError, and more — cross-cutting concerns without polluting business logic.
- [Error Handling](https://better-drizzle.com/docs/advanced/error-handling): BetterDrizzleError, structured error codes, database error detection, and constraint violation helpers.
- [Raw SQL](https://better-drizzle.com/docs/advanced/raw-sql): $raw, $executeRaw, and $rawUnsafe — safe raw SQL with comment metadata, timeouts, and dialect guards.

## Plugins

- [Plugin Overview](https://better-drizzle.com/docs/plugins/overview): How the plugin system works — setup, hooks, transforms, extensions, and operation args.
- [Rules](https://better-drizzle.com/docs/plugins/rules): Official rules plugin — runtime guardrails for raw SQL, destructive writes, pagination, locks, and request context.
- [Soft Delete](https://better-drizzle.com/docs/plugins/soft-delete): Official soft delete plugin — marks rows as deleted instead of removing them.
- [Timestamps](https://better-drizzle.com/docs/plugins/timestamps): Official timestamps plugin — auto-manages createdAt and updatedAt columns.
- [Writing Plugins](https://better-drizzle.com/docs/plugins/writing-plugins): Build your own plugin — extend clients, models, hooks, transforms, and operation args.

## Guides

- [Frameworks](https://better-drizzle.com/docs/guides/frameworks): Integration patterns for Bun, Express, Fastify, Next.js, and other runtimes.
- [Service Patterns](https://better-drizzle.com/docs/guides/service-patterns): Structuring application code with better-drizzle — repositories, services, and dependency injection.
- [Multi-Tenancy & Request Context](https://better-drizzle.com/docs/guides/multi-tenancy): Thread tenant and request metadata through hooks, plugins, and transactions with meta and $withContext.
- [Dynamic Repositories](https://better-drizzle.com/docs/guides/dynamic-repositories): Resolve delegates at runtime by schema key or database table name.
- [Migrating from Drizzle](https://better-drizzle.com/docs/guides/migrating-from-drizzle): Step-by-step guide for adding better-drizzle to an existing Drizzle project.
- [Limitations](https://better-drizzle.com/docs/guides/limitations): Known boundaries, unsupported patterns, and where raw Drizzle is the better choice.

## Performance

- [Benchmarks](https://better-drizzle.com/docs/performance/benchmarks): Latency, throughput, and memory overhead comparisons against raw Drizzle.
- [API Parity](https://better-drizzle.com/docs/performance/parity): Fair comparison methodology — better-drizzle and raw Drizzle doing the same effective work.

## Reference

- [Client API](https://better-drizzle.com/docs/reference/client): better() options, client-level methods, and exports.
- [Model API](https://better-drizzle.com/docs/reference/model-api): Per-table delegate methods — CRUD, queries, pagination, and batch operations.
- [Query Options](https://better-drizzle.com/docs/reference/query-options): where, select, include, orderBy, take, skip, and cursor — fully typed.
- [Error Reference](https://better-drizzle.com/docs/reference/errors): BetterDrizzleError codes, status mapping, and database error detection helpers.
- [Support Matrix](https://better-drizzle.com/docs/reference/support-matrix): Driver and dialect support for every feature.
- [Stability](https://better-drizzle.com/docs/reference/stability): API stability guarantees and versioning policy.

## Optional

- [GitHub Repository](https://github.com/almeidazs/better-drizzle): Source code, issues, and contributions.
- [npm Package](https://www.npmjs.com/package/better-drizzle): Install better-drizzle from npm.
- [Examples](https://github.com/almeidazs/better-drizzle/tree/main/examples): Markdown-first example catalog covering basics, frameworks, plugins, and performance.