WIP

Author: ymc9

versioned_docs/version-3.x/_components/ZModelVsPSL.tsx

@@ -0,0 +1,16 @@
+import React, { FC } from 'react';
+import Admonition from '@theme/Admonition';
+
+interface ZModelVsPSLProps {
+    children: React.ReactNode;
+}
+
+const ZModelVsPSL: FC<ZModelVsPSLProps> = ({ children }) => {
+    return (
+        <Admonition type="info" title="🔋 ZModel vs PSL">
+            {children}
+        </Admonition>
+    );
+};
+
+export default ZModelVsPSL;

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

@@ -1,4 +1,4 @@
-position: 3
+position: 4
 label: Migration
 collapsible: true
 collapsed: true

versioned_docs/version-3.x/migration/introduction.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+description: ZenStack migration overview
+---
+
+# Overview

versioned_docs/version-3.x/migration/overview.md

@@ -1,7 +1,7 @@
-position: 3
-label: Writing Schema
+position: 2
+label: Data Modeling
 collapsible: true
 collapsed: true
 link:
     type: generated-index
-    title: Writing Schema
+    title: Data Modeling

versioned_docs/version-3.x/orm/zmodel/_category_.yml renamed to versioned_docs/version-3.x/modeling/_category_.yml

@@ -0,0 +1,47 @@
+---
+sidebar_position: 4
+description: Attributes in ZModel
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Attribute
+
+Attributes allow you to attach metadata to models and fields. As you've seen in the previous sections, they are used for many purposes, like adding unique constraints, mapping names, etc. Attributes are also indispensable for modeling relations between models.
+
+## Naming conventions
+
+By convention, attributes attached to models use a double `@@` prefix, while those for fields use a single `@` prefix.
+
+```zmodel
+model User {
+    id        Int    @id
+    email     String @unique
+
+    @@index([email, name])
+}
+```
+
+## Defining and applying attributes
+
+<ZModelVsPSL>
+Prisma schema doesn't allow users to define custom attributes, while ZModel allows it and uses it as a key mechanism for extensibility.
+</ZModelVsPSL>
+
+ZModel comes with a rich set of attributes that you can use directly. See [ZModel Language Reference](../reference/zmodel-language.md) for a complete list. You can also define your own custom attributes for specific purposes. Attributes are defined with a list of typed parameters. Parameters can named (default) or positional. Positional parameters can be passed with or without an explicit name. Parameters can also be optional.
+
+Here's an example for how the `@unique` attribute is defined:
+
+```zmodel
+attribute @unique(map: String?, length: Int?, sort: SortOrder?)
+```
+
+You can apply it in various ways:
+
+```zmodel
+model Foo {
+    x String @unique() // default application
+    y String @unique('y_unique') // positional parameter
+    z String @unique(map: 'z_unique', length: 10) // named parameter
+}
+```

versioned_docs/version-3.x/modeling/attribute.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 7
+description: Custom types in ZModel
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Custom Type
+
+<ZModelVsPSL>
+Custom type is a ZModel concept and doesn't exist in PSL.
+</ZModelVsPSL>
+
+Besides models, you can also define custom types to encapsulate complex data structures. The main difference between a model and a custom type is that the latter is not backed by a database table.
+
+Here's a simple example:
+
+```zmodel
+type Address {
+    street  String
+    city    String
+    country String
+    zip     Int
+}
+```
+
+Custom types are defined exactly like models, with the exception that they cannot contain fields that are relations to other models. They can, however, contain fields that are other custom types.
+
+There are two ways to use custom types:
+
+```zmodel
+type Address {
+    street  String
+    city    String
+    country String
+    zip     Int
+}
+
+type UserProfile {
+    gender  String
+    address Address?
+}
+```
+
+- [Mixin](./mixin.md)
+- [Strongly typed JSON fields](./strong-typed-json.md)

versioned_docs/version-3.x/modeling/custom-type.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+description: Datasource in ZModel
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Data Source
+
+The `datasource` block provides information about the database your application uses. The ORM relies on it to determine the proper SQL dialect to use when generating queries. If you use [Migration](../migration/), it must also have a `url` field that specifies the database connection string, so that the migration engine knows how to connect to the database. The `env` function can be used to reference environment variables so you can keep sensitive information out of the code.
+
+:::tip
+You can use both single quote and double quote for string literals.
+:::
+
+Each ZModel schema must have exactly one `datasource` block.
+
+<Tabs>
+
+<TabItem value="postgresql" label="PostgreSQL" default>
+```zmodel
+datasource db {
+    provider = 'postgresql'
+    url      = env('DATABASE_URL')
+}
+```
+</TabItem>
+
+<TabItem value="sqlite" label="SQLite">
+```zmodel
+datasource db {
+    provider = 'sqlite'
+    url      = 'file:./dev.db'
+}
+```
+</TabItem>
+
+</Tabs>
+
+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.
+
+<ZModelVsPSL>
+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/) section.
+</ZModelVsPSL>

versioned_docs/version-3.x/modeling/datasource.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 4
+description: Enums in ZModel
+---
+
+# Enum
+
+Enums are simple constructs that allow you to define a set of named values.
+
+```zmodel
+enum Role {
+    USER
+    ADMIN
+}
+```
+
+They can be used to type model fields:
+
+```zmodel
+model User {
+    id   Int  @id
+    // highlight-next-line
+    role Role @default(USER)
+}
+```
+
+Enum field names are added to the global scope and are resolved without qualification. You need to make sure they don't collide with other global names.

versioned_docs/version-3.x/modeling/enum.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 8
+description: Reusing common fields with mixins
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Mixin
+
+<ZModelVsPSL>
+Mixin is a ZModel concept and don't exist in PSL.
+</ZModelVsPSL>
+
+:::info
+Mixin was previously known as "abstract inheritance" in ZenStack v2. It's renamed and changed to use the `with` keyword to distinguish from polymorphic model inheritance.
+:::
+
+Very often you'll find many of your models share quite a few common fields. It's tedious and error-prone to repeat them. As a rescue, you can put those fields into custom types, and "mix-in" them into your models.
+
+***Before:***
+
+```zmodel
+model User {
+    id        String @id
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+    email     String @unique
+}
+```
+
+***After:***
+
+```zmodel
+type BaseFieldsMixin {
+    id        String   @id
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+}
+
+model User with BaseFieldsMixin {
+    email String @unique
+}
+```
+
+A model can use multiple mixins as long as their field names don't conflict.
+
+Mixins don't exist at the database level. The fields defined in the mixin types are conceptually inlined into the models that use them.