From 227654b09801b9ae9091c62caef3b9e0c1c690f3 Mon Sep 17 00:00:00 2001 From: ymc9 <104139426+ymc9@users.noreply.github.com> Date: Mon, 10 Nov 2025 10:14:09 -0800 Subject: [PATCH 1/2] doc: v3 postgres multi-schema guide --- src/pages/v3/_components/Service.tsx | 6 +-- .../version-3.x/recipe/_category_.yml | 4 ++ .../recipe/postgres-multi-schema.md | 51 +++++++++++++++++++ .../version-3.x/reference/zmodel/attribute.md | 16 ++++++ .../reference/zmodel/datasource.md | 8 +++ 5 files changed, 82 insertions(+), 3 deletions(-) create mode 100644 versioned_docs/version-3.x/recipe/_category_.yml create mode 100644 versioned_docs/version-3.x/recipe/postgres-multi-schema.md diff --git a/src/pages/v3/_components/Service.tsx b/src/pages/v3/_components/Service.tsx index ad14b2d3..b0641ec6 100644 --- a/src/pages/v3/_components/Service.tsx +++ b/src/pages/v3/_components/Service.tsx @@ -75,12 +75,12 @@ export { {`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 } }); diff --git a/versioned_docs/version-3.x/recipe/_category_.yml b/versioned_docs/version-3.x/recipe/_category_.yml new file mode 100644 index 00000000..67bd5fa5 --- /dev/null +++ b/versioned_docs/version-3.x/recipe/_category_.yml @@ -0,0 +1,4 @@ +position: 7 +label: Recipes +collapsible: true +collapsed: true diff --git a/versioned_docs/version-3.x/recipe/postgres-multi-schema.md b/versioned_docs/version-3.x/recipe/postgres-multi-schema.md new file mode 100644 index 00000000..cedb9c3c --- /dev/null +++ b/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. diff --git a/versioned_docs/version-3.x/reference/zmodel/attribute.md b/versioned_docs/version-3.x/reference/zmodel/attribute.md index 7e299e8b..f5be540b 100644 --- a/versioned_docs/version-3.x/reference/zmodel/attribute.md +++ b/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 diff --git a/versioned_docs/version-3.x/reference/zmodel/datasource.md b/versioned_docs/version-3.x/reference/zmodel/datasource.md index 2213ed6f..a62a782b 100644 --- a/versioned_docs/version-3.x/reference/zmodel/datasource.md +++ b/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 From 74ac513148e4670efeb46b25fd7daf09d7b8b117 Mon Sep 17 00:00:00 2001 From: ymc9 <104139426+ymc9@users.noreply.github.com> Date: Wed, 12 Nov 2025 07:41:46 -0800 Subject: [PATCH 2/2] update --- versioned_docs/version-3.x/migrate-prisma.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-3.x/migrate-prisma.md b/versioned_docs/version-3.x/migrate-prisma.md index 7b979753..d58681a8 100644 --- a/versioned_docs/version-3.x/migrate-prisma.md +++ b/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 | |