doc: v3 postgres multi-schema guide (#505)

* doc: v3 postgres multi-schema guide * update

Author: ymc9

src/pages/v3/_components/Service.tsx

@@ -75,12 +75,12 @@ export {
  <TabItem label="Client Code" value="client">
  <CodeBlock language="tsx" title="React Example" className="p-4 xl:text-lg">
  {`import { schema } from './zenstack';
-import { useQueryHooks } from '@zenstackhq/query/react';
+import { useClientQueries } from '@zenstackhq/tanstack-query/react';
 
 export function UserPosts({ userId }: { userId: number }) {
  // use auto-generated hook to query user with posts
- const { user: userHooks } = useQueryHooks(schema);
- const { data, isLoading } = userHooks.useFindUnique({
+ const client = useClientQueries(schema);
+ const { data, isLoading } = client.user.useFindUnique({
  where: { id: userId },
  include: { posts: true }
  });

versioned_docs/version-3.x/migrate-prisma.md

@@ -270,4 +270,4 @@ Here's a list of Prisma features that are not supported in ZenStack v3:
 | [JSON Filters](https://www.prisma.io/docs/orm/reference/prisma-client-reference#json-filters) | Yes | |
 | [Full-Text Search](https://www.prisma.io/docs/orm/prisma-client/queries/full-text-search) | Yes | |
 | [Comparing Columns](https://www.prisma.io/docs/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) | Yes | |
-| [Postgres Multi-Schema](https://www.prisma.io/docs/orm/prisma-schema/data-model/multi-schema) | Yes | |
+| [Database Seeding](https://www.prisma.io/docs/orm/prisma-migrate/workflows/seeding) | Yes | |

versioned_docs/version-3.x/recipe/_category_.yml

@@ -0,0 +1,4 @@
+position: 7
+label: Recipes
+collapsible: true
+collapsed: true

versioned_docs/version-3.x/recipe/postgres-multi-schema.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+# Working With PostgreSQL Schemas
+
+PostgreSQL has the concept of [Schema](https://www.postgresql.org/docs/current/ddl-schemas.html) that allows you to organize database objects into logical groups. This guide explains how to use multiple schemas in PostgreSQL with ZenStack.
+
+Please note that the "Schema" term used in this guide refers specifically to the PostgreSQL concept, and has nothing to do with generic database schemas or the ZModel schema.
+
+## Default Schema
+
+By default, ZenStack assumes that all your models are in the default "public" schema and prepends table names with `public.` when generating SQL queries. You can change the default schema in the `datasource` block of ZModel:
+
+```zmodel
+datasource db {
+ provider = 'postgresql'
+ defaultSchema = 'my_schema'
+}
+```
+
+:::info
+If you're migrating from Prisma, you may have set the schema on the database url with the `?schema=` query parameter. This is not supported in ZenStack.
+:::
+
+## Using Multiple Schemas
+
+If you use multiple Postgres schemas, you can add a `schemas` field to the datasource block, and then use the `@@schema` attribute to specify the schema to use for each model:
+
+```zmodel
+datasource db {
+ provider = 'postgresql'
+ schemas = ['auth', 'post']
+}
+
+model User {
+ id Int @id @default(autoincrement())
+ name String
+
+ @@schema('auth')
+}
+
+model Post {
+ id Int @id @default(autoincrement())
+ title String
+
+ @@schema('post')
+}
+```
+
+For models that don't have the `@@schema` attribute, the default schema (either "public" or the one specified in `defaultSchema`) will be used.

versioned_docs/version-3.x/reference/zmodel/attribute.md

@@ -374,6 +374,22 @@ model User {
 }
 ```
 
+### @@schema
+
+```zmodel
+attribute @@schema(_ map: String)
+```
+
+Specifies the schema to use in a multi-schema PostgreSQL database. See [Working With PostgreSQL Schemas](../../recipe/postgres-multi-schema.md) for more details.
+
+```zmodel
+model User {
+ id Int @id
+ name String
+ @@schema("auth")
+}
+```
+
 ### @id
 
 ```zmodel

versioned_docs/version-3.x/reference/zmodel/datasource.md

@@ -32,6 +32,14 @@ datasource NAME {
 
  The `url` option is only used by the migration engine to connect to the database. The ORM runtime doesn't rely on it. Instead, you provide the connection information when constructing an ORM client.
 
+- **`defaultSchema`**:
+
+ (PostgreSQL only) The default schema to use for models that don't have an explicit `@@schema` attribute. Defaults to "public". See [Working With PostgreSQL Schemas](../../recipe/postgres-multi-schema.md) for more details.
+
+- **`schemas`**:
+
+ (PostgreSQL only) List of schemas to use. If specified, you can use the `@@schema` attribute to specify the schema name for a model. See [Working With PostgreSQL Schemas](../../recipe/postgres-multi-schema.md) for more details.
+
 ## Example
 
 ```zmodel