From 9de12dc1de40ccc01093bc2860e131f323436956 Mon Sep 17 00:00:00 2001 From: DukeManh Date: Sat, 16 Apr 2022 17:40:42 -0400 Subject: [PATCH 1/2] Add Telescope Prisma docs --- .../docs/tools-and-technologies/prisma.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 src/web/docusaurus/docs/tools-and-technologies/prisma.md diff --git a/src/web/docusaurus/docs/tools-and-technologies/prisma.md b/src/web/docusaurus/docs/tools-and-technologies/prisma.md new file mode 100644 index 0000000000..740f8d2218 --- /dev/null +++ b/src/web/docusaurus/docs/tools-and-technologies/prisma.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 11 +--- + +# Prisma + +## Our Database + +[Supabase](./supabase.md) is one of the technologies that Telescope uses. Because it is built on top of Postgres, we have full access to a Postgres DB that can be used to store all sorts of data used by both frontend and backend. + +> PostgreSQL is a highly stable database backed by more than 20 years of development by the open-source community. + +## Database Schema + +Our database schema is defined in [schema.prisma](https://github.com/Seneca-CDOT/telescope/blob/master/src/db/prisma/schema.prisma). This is where we defined models and their relations using Prisma schema syntax. + +Managing the database schema using Prisma, we can track granular changes to the database schema. These granular changes are reflected as separate SQL script files. That way, our granular schema changes are reflected as code that can be captured with any version control software. This makes sure that the local development database or the production database is always up to date with the latest Schema. + +## Database migration + +Whenever we start up the DB container or after updating our schema, we should run a migration to apply new changes to the database if any. + +## Running migration + +```bash + cd src/db + cp env.example .env + pnpm migrate +``` + +See also [DB maintenance on staging and production](../contributing/database-maintenance.md). + +## Creating migration + +For a migration that has "narrowing" nature such as dropping a table, dropping a column or converting data types or similar changes, running a migration requires attention to make sure the data loss is under control. Prisma is smart enough to warn us about any potential data loss. + +### Schema change + +Simply edit the schema in [schema.prisma](https://github.com/Seneca-CDOT/telescope/blob/master/src/db/prisma/schema.prisma) and apply the migration. + +```bash + cd src/db + cp env.example .env + pnpm migrate +``` + +### Custom migration + +Sometimes, we want to make changes other than the modifying the schema, for example, adding new RLS to a table. We can do so by creating an empty migration file, which is an empty SQL script where we write our own SQL queries to be apply to the database. + +```bash + cd src/db + cp env.example .env + pnpm create-migration +``` + +Write SQL query inside the newly created `migration.sql`. + +```bash + pnpm migrate +``` From d915093aebd9874bed03ee7844aefcef73b5ab29 Mon Sep 17 00:00:00 2001 From: DukeManh Date: Sun, 17 Apr 2022 12:28:27 -0400 Subject: [PATCH 2/2] fix change request --- src/web/docusaurus/docs/tools-and-technologies/prisma.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/web/docusaurus/docs/tools-and-technologies/prisma.md b/src/web/docusaurus/docs/tools-and-technologies/prisma.md index 740f8d2218..68e4969c65 100644 --- a/src/web/docusaurus/docs/tools-and-technologies/prisma.md +++ b/src/web/docusaurus/docs/tools-and-technologies/prisma.md @@ -12,7 +12,7 @@ sidebar_position: 11 ## Database Schema -Our database schema is defined in [schema.prisma](https://github.com/Seneca-CDOT/telescope/blob/master/src/db/prisma/schema.prisma). This is where we defined models and their relations using Prisma schema syntax. +Our database schema is defined in [schema.prisma](https://github.com/Seneca-CDOT/telescope/blob/master/src/db/prisma/schema.prisma). This is where we define models and their relations using Prisma's schema syntax. Managing the database schema using Prisma, we can track granular changes to the database schema. These granular changes are reflected as separate SQL script files. That way, our granular schema changes are reflected as code that can be captured with any version control software. This makes sure that the local development database or the production database is always up to date with the latest Schema. @@ -32,7 +32,7 @@ See also [DB maintenance on staging and production](../contributing/database-mai ## Creating migration -For a migration that has "narrowing" nature such as dropping a table, dropping a column or converting data types or similar changes, running a migration requires attention to make sure the data loss is under control. Prisma is smart enough to warn us about any potential data loss. +For a migration that has a "narrowing" nature such as dropping a table, dropping a column or converting data types or similar changes, running a migration requires attention to make sure the data loss is under control. Prisma is smart enough to warn us about any potential data loss. ### Schema change @@ -46,7 +46,7 @@ Simply edit the schema in [schema.prisma](https://github.com/Seneca-CDOT/telesco ### Custom migration -Sometimes, we want to make changes other than the modifying the schema, for example, adding new RLS to a table. We can do so by creating an empty migration file, which is an empty SQL script where we write our own SQL queries to be apply to the database. +Sometimes, we want to make changes other than the modifying the schema, for example, adding new RLS policies to a table. We can do so by creating an empty migration file, which is an empty SQL script where we write our own SQL queries to be applied to the database. ```bash cd src/db @@ -54,7 +54,7 @@ Sometimes, we want to make changes other than the modifying the schema, for exam pnpm create-migration ``` -Write SQL query inside the newly created `migration.sql`. +After creating the empty migration file, you can write SQL queries inside the newly created `migration.sql`. After writing the desired statements, you can apply the migration: ```bash pnpm migrate