Drizzle
Drizzle is a modern, type-safe TypeScript ORM designed for Node.js. It offers a concise and easy-to-use API, supports databases such as PostgreSQL, MySQL, and SQLite, and has powerful query builders, transaction processing, and database migration capabilities. At the same time, it remains lightweight and has no external dependencies, making it very suitable for database operation scenarios that require high performance and type safety.
@gqloom/drizzle
provides the integration of GQLoom and Drizzle:
- Use Drizzle Table as Silk;
- Use the resolver factory to quickly create CRUD operations from Drizzle.
Installation
Please refer to Drizzle's Getting Started Guide to install Drizzle and its corresponding database integration.
After installing Drizzle, install @gqloom/drizzle
:
Using Silk
We can easily use Drizzle Schemas as Silk by simply wrapping them with drizzleSilk
.
Let's use them in the resolver. At the same time, we use the useSelectedColumns()
function to know which columns are needed for the current GraphQL query:
As shown in the code above, we can directly use the Drizzle Table wrapped by drizzleSilk
in the resolver
.
Here, we use users
as the parent type of resolver.of
, and define two queries named user
and users
and a field named posts
in the resolver. Among them:
- The return type of
user
isusers.$nullable()
, indicating thatuser
may be null; - The return type of
users
isusers.$list()
, indicating thatusers
will return a list ofusers
; - The return type of the
posts
field isposts.$list()
. In theposts
field, we use theuserList
parameter in theload
method. TypeScript will help us infer its type. Theload
method is a wrapper ofDataLoader
, allowing us to quickly define aDataLoader
method and use it to batch fetchposts
.
We also use the useSelectedColumns()
function to determine which columns need to be selected for the current GraphQL query. This function requires enabling context.
For runtimes where the useSelectedColumns()
function cannot be used, we can also use the getSelectedColumns()
function to obtain the columns that need to be selected for the current query.
Derived Fields
Adding derived Fields to a database table is quite simple. However, it's important to use the field().derivedFrom()
method to declare the columns on which the computed property depends, so that the useSelectedColumns
method can correctly select these columns:
Hiding Fields
Sometimes we don't want to expose all fields of the database table to the client.
Consider that we have a users
table containing a password field, where the password
field is an encrypted password, and we don't want to expose it to the client:
We can use field.hidden
in the resolver to hide the password
field:
Resolver Factory
gqloom/drizzle
provides a resolver factory DrizzleResolverFactory
to easily create CRUD resolvers from Drizzle, and it also supports custom parameters and adding middleware.
Relationship Fields
In Drizzle Table, we can easily create relationships. We can use the relationField
method of the resolver factory to create corresponding GraphQL fields for relationships.
Queries
The Drizzle resolver factory pre-defines some commonly used queries:
selectArrayQuery
: Find multiple records in the corresponding table according to the conditions.selectSingleQuery
: Find a single record in the corresponding table according to the conditions.countQuery
: Count the number of records in the corresponding table according to the conditions.
We can use the queries from the resolver factory in the resolver:
Mutations
The Drizzle resolver factory predefines some commonly used mutations:
insertArrayMutation
: Insert multiple records.insertSingleMutation
: Insert a single record.updateMutation
: Update records.deleteMutation
: Delete records.
We can use the mutations from the resolver factory in the resolver:
Custom Input
The pre-defined queries and mutations of the resolver factory support custom input. You can define the input type through the input
option:
In the above code, we use valibot
to define the input type. v.object({ id: v.number() })
defines the type of the input object, and v.transform(({ id }) => ({ where: eq(users.id, id) }))
converts the input parameters into Drizzle query parameters.
Adding Middleware
The pre-defined queries, mutations, and fields of the resolver factory support adding middleware. You can define middleware through the middlewares
option:
In the above code, we use the middlewares
option to define middleware. async (next) => { ... }
defines a middleware. useAuthedUser()
is a custom function used to get the currently logged-in user. If the user is not logged in, an error is thrown; otherwise, next()
is called to continue execution.
Complete Resolver
We can directly create a complete Resolver with the resolver factory:
There are two functions for creating Resolvers:
usersResolverFactory.queriesResolver()
: Creates a Resolver that only includes queries and relational fields.usersResolverFactory.resolver()
: Creates a Resolver that includes all queries, mutations, and relational fields.
Custom Type Mapping
To adapt to more Drizzle types, we can extend GQLoom to add more type mappings.
First, we use DrizzleWeaver.config
to define the configuration of type mapping. Here we import GraphQLDateTime
and GraphQLJSONObject
from graphql-scalars. When encountering date
and json
types, we map them to the corresponding GraphQL scalars.
Pass the configuration to the weave
function when weaving the GraphQL Schema:
Default Type Mapping
The following table lists the default mapping relationships between Drizzle dataType
and GraphQL types in GQLoom:
Drizzle dataType | GraphQL Type |
---|---|
boolean | GraphQLBoolean |
number | GraphQLFloat |
json | GraphQLString |
date | GraphQLString |
bigint | GraphQLString |
string | GraphQLString |
buffer | GraphQLList |
array | GraphQLList |