Skip to content

doc: formatting IDs #536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ymc9 merged 5 commits into from
Dec 30, 2025
Merged

doc: formatting IDs #536

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
92c5603
doc: formatting IDs
sanny-io Dec 25, 2025
fc9343d
doc: move default value generator doc to the "modeling" part, add par…
ymc9 Dec 30, 2025
6718a54
doc: add links to function ref
ymc9 Dec 30, 2025
208ee54
remove the unused md file
ymc9 Dec 30, 2025
0e9857e
update
ymc9 Dec 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions docs/modeling/model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,15 +144,17 @@ model User {
}
```

### Default values

A default value can be specified for a field with the `@default` attribute. The value can be a literal, an enum value, or a supported function call, including:

- `now()`: returns the current timestamp
- `cuid()`: returns a CUID
- `uuid()`: returns a UUID
- `ulid()`: returns a ULID
- `nanoid()`: returns a Nano ID
- `autoincrement()`: returns an auto-incrementing integer (only for integer fields)
- `dbgenerated("...")`: calls a native db function
- [`now()`](../reference/zmodel/function.md#now): returns the current timestamp
- [`cuid()`](../reference/zmodel/function.md#cuid): returns a CUID
- [`uuid()`](../reference/zmodel/function.md#uuid): returns a UUID
- [`ulid()`](../reference/zmodel/function.md#ulid): returns a ULID
- [`nanoid()`](../reference/zmodel/function.md#nanoid): returns a Nano ID
- [`autoincrement()`](../reference/zmodel/function.md#autoincrement): returns an auto-incrementing integer (only for integer fields)
- [`dbgenerated("...")`](../reference/zmodel/function.md#dbgenerated): calls a native db function

```zmodel
model User {
Expand All @@ -162,6 +164,15 @@ model User {
}
```

Prefixing and suffixing entity IDs is becoming more common in database design, usually by including the model name in the generated ID. To support this pattern, functions that generate `String` IDs (`cuid()`, `uuid()`, `ulid()`, `nanoid()`) takes an optional `format` argument to allow passing in a pattern that controls the output format. `%s` in the pattern will be replaced by the generated id. For example:

```zmodel
model User {
// generate a UUID v4 with "user_" prefix
id String @id @default(uuid(4, "user_%s"))
}
```

## Native type mapping

Besides giving a field a type, you can also specify the native database type to use with the `@db.` series of attributes.
Expand Down
29 changes: 24 additions & 5 deletions docs/reference/zmodel/function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,35 +89,54 @@ Functions related to input validation are documented in a [separate page](./inpu
### uuid()

```zmodel
function uuid(): String {}
function uuid(version: Int?, format: String?): String {}
```

Generates a globally unique identifier based on the UUID spec.

*Parameters:*

- `version` (optional): The UUID version to generate. Supported values are `4` (default) and `7`.
- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.

### cuid()

```zmodel
function cuid(version: Int?): String {}
function cuid(version: Int?, format: String?): String {}
```

Generates a unique identifier based on the [CUID](https://github.com/ericelliott/cuid) spec. Pass `2` as an argument to use [cuid2](https://github.com/paralleldrive/cuid2).
Generates a unique identifier based on the [CUID](https://github.com/ericelliott/cuid) spec.

*Parameters:*

- `version` (optional): The CUID version to generate. Supported values are `1` (default) and `2`.
- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.

### nanoid()

```zmodel
function nanoid(length: Int?): String {}
function nanoid(length: Int?, format: String?): String {}
```

Generates an identifier based on the [nanoid](https://github.com/ai/nanoid) spec.

*Parameters:*

- `length` (optional): The length of the generated id.
- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.

### ulid()

```zmodel
function ulid(): String {}
function ulid(format: String?): String {}
```

Generates a unique identifier based on the [ULID](https://github.com/ulid/spec) spec.

*Parameters:*

- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.

### now()

```zmodel
Expand Down