From 4a469ee7d4ef8d6e93c9c7063875433df031c1e0 Mon Sep 17 00:00:00 2001 From: James Conlon Date: Sun, 27 Oct 2024 16:49:38 +0100 Subject: [PATCH 1/3] docs: add drizzle docs --- www/src/pages/en/usage/drizzle.md | 63 ++++++++++++++++++++++++++++++ www/src/pages/en/usage/drizzle.mdx | 14 ------- 2 files changed, 63 insertions(+), 14 deletions(-) create mode 100644 www/src/pages/en/usage/drizzle.md delete mode 100644 www/src/pages/en/usage/drizzle.mdx diff --git a/www/src/pages/en/usage/drizzle.md b/www/src/pages/en/usage/drizzle.md new file mode 100644 index 0000000000..1b22fc5ac7 --- /dev/null +++ b/www/src/pages/en/usage/drizzle.md @@ -0,0 +1,63 @@ +--- +title: Drizzle +description: Usage of Drizzle +layout: ../../../layouts/docs.astro +lang: en +--- + +Drizzle is an ORM for TypeScript, that allows you to define your database schema and models in a `schema.ts` file, and then generate a type-safe client that can be used to interact with your database from your backend. + +Drizzle is three major components + +- `drizzle-orm`: the ORM itself. Installed as a dependency. +- `drizzle-kit`: a CLI app used for managing migrations. Installed as a dependency. +- `drizzle-studio`: a GUI for managing you database. Installed as part of drizzle-kit. + +## Drizzle Config + +Located at `/drizzle.config.ts`. Here you can customize options like where your schema and migrations are located. Credentials provided here will be used by drizzle-kit for performing migrations. [Drizzle Documentation](https://orm.drizzle.team/docs/drizzle-config-file) + +## Drizzle Client + +Located at `src/server/db/index.ts`. The Drizzle Client is instantiated as a global variable and exported to be used in your API routes. We include the Drizzle Client in [Context](/en/usage/trpc#-serverapitrpcts) by default and recommend using this instead of importing it separately in each file. Credentials provided here will be used at runtime by drizzle-orm. + +## Drizzle Schema + +Located at `src/server/db/schema.ts`. This file is where you define your database schema and models. For those familiar with Prisma, the concepts remain the same but the syntax is different. The entire file is written in plain Typescript meaning it's a little more verbose. A major advantage however, is that schema types are applied immediately on save without the need to re-generate types after every change. [Drizzle Documentation](https://orm.drizzle.team/docs/sql-schema-declaration) + +### With NextAuth.js + +When you select NextAuth.js in combination with Drizzle, the schema file is generated and set up for you with the recommended values for the `User`, `Session`, `Account`, and `VerificationToken` models, as per the [NextAuth.js documentation](https://authjs.dev/getting-started/adapters/drizzle). + +## Default Database + +The default database is an SQLite database, which is great for development and quickly spinning up a proof-of-concept but is not recommended for production. You can change the database to use by changing the `provider` in the `datasource` block to either `postgresql` or `mysql`, and then updating the connection string within environment variables to point to your database. + +## Commands + +T3 app installs Drizzle with the following commands. They can be run with `pnpm run`. + +- `db:generate` Generate new migrations based on the current schema. +- `db:migrate` Apply migrations to the database. +- `db:push` Apply current schema to the database without creating migrations. Typically used in early stages for rapid prototyping. +- `db:studio` View database in Drizzle studio. + +## Migrations + +Migrations data is stored in `/Drizzle`. Drizzle will modify these files automatically whenever changes are executed against the database. It is not recommended to modify these files manually. By default, a log of all successful migrations is also stored in a `__drizzle_migrations` table in the database (PostgreSQL only). + +- A log of every migration applied to the database is stored in `_journal.json`. +- Individual migrations are stored as pure SQL files. These are numbered and given a jaunty name e.g. `0000_salty_the_spike.sql` +- Additionally, each migration gets its own snapshot file which represents the database state directly after that migration e.g. `0000_snapshot.json` + +## Database Vendors + +Drizzle comes with drivers for standard PostgreSQL, MySQL and SQLite connections. These will handle the majority of cases. It also comes bundled with a host of drivers for some of the most popular online database vendors. These may not be strictly necessary to create a connection but will allow you to utilize more advanced behaviours like http/websocket connections. Detailed instructions for all the major vendors can be found [here](https://orm.drizzle.team/docs/get-started). + +## Useful Resources + +| Resource | Link | +| --------------------------- | --------------------------------------------------- | +| Drizzle Docs | https://orm.drizzle.team/docs/overview | +| Drizzle GitHub | https://github.com/drizzle-team/drizzle-orm | +| NextAuth.JS Drizzle Adapter | https://authjs.dev/getting-started/adapters/drizzle | diff --git a/www/src/pages/en/usage/drizzle.mdx b/www/src/pages/en/usage/drizzle.mdx deleted file mode 100644 index aefe547554..0000000000 --- a/www/src/pages/en/usage/drizzle.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Drizzle -description: Usage of Drizzle -layout: ../../../layouts/docs.astro -lang: en -isMdx: true ---- - -import Callout from "../../../components/docs/callout.tsx"; - - - The `drizzle` option is a new addition and no docs have yet been written. Contributions are welcome! - - From 7c21aefc9da0ecb778182c1c72ea67b19708e8d8 Mon Sep 17 00:00:00 2001 From: James Conlon Date: Wed, 6 Nov 2024 22:59:03 +0100 Subject: [PATCH 2/3] update paragraph on default database --- www/.astro/settings.json | 5 +++++ www/src/pages/en/usage/drizzle.md | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 www/.astro/settings.json diff --git a/www/.astro/settings.json b/www/.astro/settings.json new file mode 100644 index 0000000000..ee75d45167 --- /dev/null +++ b/www/.astro/settings.json @@ -0,0 +1,5 @@ +{ + "_variables": { + "lastUpdateCheck": 1730044581130 + } +} \ No newline at end of file diff --git a/www/src/pages/en/usage/drizzle.md b/www/src/pages/en/usage/drizzle.md index 1b22fc5ac7..57ef2f596f 100644 --- a/www/src/pages/en/usage/drizzle.md +++ b/www/src/pages/en/usage/drizzle.md @@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro lang: en --- -Drizzle is an ORM for TypeScript, that allows you to define your database schema and models in a `schema.ts` file, and then generate a type-safe client that can be used to interact with your database from your backend. +Drizzle is an ORM for TypeScript, that allows you to define your database schema and models in a `schema.ts` file. Using the drizzle client on the backend allows you to interact with your database while maintaining complete type safety. Drizzle is three major components @@ -31,7 +31,7 @@ When you select NextAuth.js in combination with Drizzle, the schema file is gene ## Default Database -The default database is an SQLite database, which is great for development and quickly spinning up a proof-of-concept but is not recommended for production. You can change the database to use by changing the `provider` in the `datasource` block to either `postgresql` or `mysql`, and then updating the connection string within environment variables to point to your database. +The default database is a local SQLite database, which is great for development and quickly spinning up a proof-of-concept. When you wish to move on to a production database it is as simple as updating the database connection string within environment variables and changing the drizzle driver to match. For detailed instructions see [vendors](#database-vendors). ## Commands From b7dd46e18684cae16be5f50f2e1a3566db785191 Mon Sep 17 00:00:00 2001 From: James Conlon Date: Wed, 6 Nov 2024 23:00:54 +0100 Subject: [PATCH 3/3] remove astro settings file --- www/.astro/settings.json | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 www/.astro/settings.json diff --git a/www/.astro/settings.json b/www/.astro/settings.json deleted file mode 100644 index ee75d45167..0000000000 --- a/www/.astro/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "_variables": { - "lastUpdateCheck": 1730044581130 - } -} \ No newline at end of file