From a88323ab603baf2bd1f1af61b39bd5e2d4d53f21 Mon Sep 17 00:00:00 2001 From: ymc9 <104139426+ymc9@users.noreply.github.com> Date: Sun, 22 Feb 2026 19:50:27 -0500 Subject: [PATCH 1/2] doc: v3.3 incremental updates --- docs/community-packages.md | 4 ++++ docs/faq.md | 2 +- docs/migrate-prisma.md | 28 ++++++++++++++++++++++++---- docs/migrate-v2.md | 4 +--- docs/modeling/datasource.md | 2 +- docs/orm/api/filter.md | 2 +- docs/orm/api/find.md | 2 +- docs/orm/client.md | 18 ++++++++++++++++++ docs/reference/cli.md | 15 +++++++++++++++ docs/reference/zmodel/datasource.md | 3 ++- 10 files changed, 68 insertions(+), 12 deletions(-) diff --git a/docs/community-packages.md b/docs/community-packages.md index 3f1af1fa..19e76f16 100644 --- a/docs/community-packages.md +++ b/docs/community-packages.md @@ -7,6 +7,10 @@ sidebar_label: Community Packages ZenStack plugins built by our awesome community members :heart:. +- [zenstack-encrypt](https://github.com/genu/zenstack-encryption) + + Transparent field-level encryption and decryption using the `@encrypted` attribute. Made by [@genu](https://github.com/genu). + - [zenstack-cache](https://github.com/visualbravo/zenstack-cache) Reduce response times and database load with query-level caching integrated with the ZenStack ORM. Made by [@sanny-io](https://github.com/sanny-io). diff --git a/docs/faq.md b/docs/faq.md index bc44371d..b9e665e7 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,7 +10,7 @@ sidebar_position: 100 ## What databases are supported? -Currently only SQLite (with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) or [sql.js](https://github.com/sql-js/sql.js) driver) and PostgreSQL (with [node-postgres](https://github.com/brianc/node-postgres) driver) are supported. MySQL will be added in the future. There's no plan to support other relational databases or NoSQL databases. +SQLite (with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) or [sql.js](https://github.com/sql-js/sql.js) driver), PostgreSQL (with [node-postgres](https://github.com/brianc/node-postgres) driver or [@neondatabase/serverless](https://github.com/neondatabase/serverless)), and MySQL (with [mysql2](https://github.com/sidorares/node-mysql2) driver) are supported.There's no plan to support other relational databases or NoSQL databases. ## What JavaScript runtimes are supported? diff --git a/docs/migrate-prisma.md b/docs/migrate-prisma.md index e59e3f39..a20e2516 100644 --- a/docs/migrate-prisma.md +++ b/docs/migrate-prisma.md @@ -20,7 +20,7 @@ This guide will help you migrate an existing Prisma project to ZenStack v3. The In the following sections, we'll cover various aspects of the migration process where care needs to be taken. :::warning -ZenStack v3 currently only supports PostgreSQL and SQLite databases. +ZenStack v3 only supports PostgreSQL, MySQL, and SQLite databases. ::: ## Migration Steps @@ -39,16 +39,19 @@ ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency o ZenStack doesn't bundle database drivers. Install the appropriate driver for your database: + - + + + - + - + @@ -102,6 +105,23 @@ export const db = new ZenStackClient(schema, { ``` + + +```ts title='db.ts' +import { ZenStackClient } from '@zenstackhq/orm'; +import { MysqlDialect } from '@zenstackhq/orm/dialects/mysql'; +import { schema } from './zenstack/schema'; +import { createPool } from 'mysql2'; + +export const db = new ZenStackClient(schema, { + dialect: new MysqlDialect({ + pool: createPool(process.env.DATABASE_URL), + }), +}); +``` + + + ```ts title='db.ts' diff --git a/docs/migrate-v2.md b/docs/migrate-v2.md index 0c02b28b..76624cc5 100644 --- a/docs/migrate-v2.md +++ b/docs/migrate-v2.md @@ -25,9 +25,7 @@ Here are a few essential items to verify before preparing your migration: - Database support - V3 currently only supports PostgreSQL and SQLite databases. MySQL will be added later. - - For PostgreSQL, only the traditional TCP-based connection is supported. Newer HTTP-based protocols, such as those supported by providers like Neon and Prisma PG, are not yet supported, but will be in the future. + V3 only supports PostgreSQL, MySQL and SQLite databases. - Prisma feature gaps diff --git a/docs/modeling/datasource.md b/docs/modeling/datasource.md index bbdeb7d1..d2812129 100644 --- a/docs/modeling/datasource.md +++ b/docs/modeling/datasource.md @@ -35,7 +35,7 @@ datasource db { -Currently, only PostgreSQL and SQLite are supported. MySQL will be supported in a future release. There's no plan for other relational database types or NoSQL databases. +PostgreSQL, MySQL and SQLite are supported. There's no plan for other relational database types or NoSQL databases. ZenStack's ORM runtime doesn't rely on the `url` information to connect to the database. Instead, you provide the information when constructing an ORM client — more on this in the [ORM](../orm/) part. diff --git a/docs/orm/api/filter.md b/docs/orm/api/filter.md index 7011d8ea..d17b9f63 100644 --- a/docs/orm/api/filter.md +++ b/docs/orm/api/filter.md @@ -34,7 +34,7 @@ List fields allow extra filter operators to filter on the list content: - `isEmpty`: checks if the list is empty. :::info -List type is not supported by SQLite. +List type is only supported by PostgreSQL. ::: ```zmodel diff --git a/docs/orm/api/find.md b/docs/orm/api/find.md index a7c44fc5..06f350fa 100644 --- a/docs/orm/api/find.md +++ b/docs/orm/api/find.md @@ -67,7 +67,7 @@ You can use the following fields to control what fields are returned in the resu ## Finding distinct rows -You can use the `distinct` field to find distinct rows based on specific fields. One row for each unique combination of the specified fields will be returned. The implementation relies on SQL `DISTINCT ON`, so it's not available for SQLite provider. +You can use the `distinct` field to find distinct rows based on specific fields. One row for each unique combination of the specified fields will be returned. The implementation relies on SQL `DISTINCT ON`, so it's not available for SQLite and MySQL provider. ```ts // returns one Post for each unique authorId diff --git a/docs/orm/client.md b/docs/orm/client.md index 1000d9f0..674f2ef1 100644 --- a/docs/orm/client.md +++ b/docs/orm/client.md @@ -58,6 +58,24 @@ export const db = new ZenStackClient(schema, { ``` + + + + +```ts title='db.ts' +import { ZenStackClient } from '@zenstackhq/orm'; +import { MysqlDialect } from '@zenstackhq/orm/dialects/mysql'; +import { schema } from './zenstack/schema'; +import { createPool } from 'mysql2'; + +export const db = new ZenStackClient(schema, { + dialect: new MysqlDialect({ + pool: createPool(process.env.DATABASE_URL), + }), +}); +``` + + The created `db` object has the full ORM API inferred from the type of the `schema` parameter. When necessary, you can also explicitly get the inferred client type like: diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 1729aabb..a26eb38f 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -287,6 +287,21 @@ Options: -h, --help display help for command ``` +### proxy + +Start the ZenStack proxy server. This command is aliased as `studio` too. + +```bash +Options: + --schema schema file (with extension .zmodel). Defaults to "zenstack/schema.zmodel" unless specified in package.json. + -p, --port port to run the proxy server on (default: 2311) + -o, --output output directory for `zen generate` command + -d, --databaseUrl database connection URL + -l, --logLevel Query log levels (e.g., query, error) + --no-version-check do not check for new version + -h, --help Show this help message +``` + ## Overriding Default Options ### Default Schema Location diff --git a/docs/reference/zmodel/datasource.md b/docs/reference/zmodel/datasource.md index b59ef6c1..24534589 100644 --- a/docs/reference/zmodel/datasource.md +++ b/docs/reference/zmodel/datasource.md @@ -25,10 +25,11 @@ datasource NAME { - sqlite - postgresql + - mysql - **`url`**: - Optional. Database connection string. Either a plain string or an invocation of `env` function to fetch from an environment variable. For SQLite provider, the URL should be a file protocol, like `file:./dev.db`. For PostgreSQL provider, it should be a postgres connection string, like `postgresql://user:password@localhost:5432/dbname`. + Optional. Database connection string. Either a plain string or an invocation of `env` function to fetch from an environment variable. For SQLite provider, the URL should be a file protocol, like `file:./dev.db`. For PostgreSQL and MySQL provider, it should be a valid connection string URL, like `postgresql://user:password@localhost:5432/dbname`. 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. From cb5caf59b9aa500ac360fad66b7b80c4ad40d904 Mon Sep 17 00:00:00 2001 From: ymc9 <104139426+ymc9@users.noreply.github.com> Date: Sun, 22 Feb 2026 22:30:38 -0500 Subject: [PATCH 2/2] addressing pr comments --- docs/faq.md | 2 +- docs/reference/cli.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index b9e665e7..bb975e65 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,7 +10,7 @@ sidebar_position: 100 ## What databases are supported? -SQLite (with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) or [sql.js](https://github.com/sql-js/sql.js) driver), PostgreSQL (with [node-postgres](https://github.com/brianc/node-postgres) driver or [@neondatabase/serverless](https://github.com/neondatabase/serverless)), and MySQL (with [mysql2](https://github.com/sidorares/node-mysql2) driver) are supported.There's no plan to support other relational databases or NoSQL databases. +SQLite (with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) or [sql.js](https://github.com/sql-js/sql.js) driver), PostgreSQL (with [node-postgres](https://github.com/brianc/node-postgres) driver or [@neondatabase/serverless](https://github.com/neondatabase/serverless)), and MySQL (with [mysql2](https://github.com/sidorares/node-mysql2) driver) are supported. There's no plan to support other relational databases or NoSQL databases. ## What JavaScript runtimes are supported? diff --git a/docs/reference/cli.md b/docs/reference/cli.md index a26eb38f..cf604920 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -292,6 +292,8 @@ Options: Start the ZenStack proxy server. This command is aliased as `studio` too. ```bash +Usage: zen proxy [options] + Options: --schema schema file (with extension .zmodel). Defaults to "zenstack/schema.zmodel" unless specified in package.json. -p, --port port to run the proxy server on (default: 2311)