zenstack/docs/zmodel-attribute.md

Attribute

Attributes decorate fields and data models and attach extra behaviors or constraints to them.

Syntax

Field attribute

Field attribute name is prefixed by a single @. Its application takes the following form:

id String @[ATTR_NAME](ARGS)?

• [ATTR_NAME]

Attribute name. See below for a full list of attributes.

• [ARGS]

See attribute arguments.

Data model attribute

Field attribute name is prefixed double @@. Its application takes the following form:

model Model {
    @@[ATTR_NAME](ARGS)?
}

• [ATTR_NAME]

Attribute name. See below for a full list of attributes.

• [ARGS]

See attribute arguments.

Arguments

Attribute can be declared with a list of parameters, and applied with an optional comma-separated list of arguments.

Arguments are mapped to parameters by position or by name. For example, for the @default attribute declared as:

attribute @default(_ value: ContextType)

, the following two ways of applying it are equivalent:

published Boolean @default(value: false)

published Boolean @default(false)

Parameter types

Attribute parameters are typed. The following types are supported:

• Int

  Integer literal can be passed as argument.

  E.g., declaration:

  attribute @password(saltLength: Int?, salt: String?)
  
  

  application:

  password String @password(saltLength: 10)
  

• String

  String literal can be passed as argument.

  E.g., declaration:

  attribute @id(map: String?)
  

  application:

  id String @id(map: "_id")
  

• Boolean

  Boolean literal or expression can be passed as argument.

  E.g., declaration:

  attribute @@allow(_ operation: String, _ condition: Boolean)
  

  application:

  @@allow("read", true)
  @@allow("update", auth() != null)
  

• ContextType

  A special type that represents the type of the field onto which the attribute is attached.

  E.g., declaration:

  attribute @default(_ value: ContextType)
  

  application:

  f1 String @default("hello")
  f2 Int @default(1)
  

• FieldReference

  References to fields defined in the current model.

  E.g., declaration:

  attribute @relation(
      _ name: String?,
      fields: FieldReference[]?,
      references: FieldReference[]?,
      onDelete: ReferentialAction?,
      onUpdate: ReferentialAction?,
      map: String?)
  

  application:

  model Model {
      ...
      // [ownerId] is a list of FieldReference
      owner Owner @relation(fields: [ownerId], references: [id])
      ownerId
  }
  

• Enum

  Attribute parameter can also be typed as predefined enum.

  E.g., declaration:

  attribute @relation(
      _ name: String?,
      fields: FieldReference[]?,
      references: FieldReference[]?,
      // ReferentialAction is a predefined enum
      onDelete: ReferentialAction?,
      onUpdate: ReferentialAction?,
      map: String?)
  

  application:

  model Model {
      // 'Cascade' is a predefined enum value
      owner Owner @relation(..., onDelete: Cascade)
  }
  

An attribute parameter can be typed as any of the above type, a list of the above type, or an optional of the above type.

    model Model {
        ...
        f1 String
        f2 String
        // a list of FieldReference
        @@unique([f1, f2])
    }

Attribute functions

Attribute functions are used for providing values for attribute arguments, e.g., current DateTime, an autoincrement Int, etc. They can be used in place of attribute argument, like:

model Model {
    ...
    serial Int @default(autoincrement())
    createdAt DateTime @default(now())
}

You can find a list of predefined attribute functions here.

Predefined attributes

Field attributes

• @id

  attribute @id(map: String?)
  

  Defines an ID on the model.

  Params:

  Name	Description
  map	The name of the underlying primary key constraint in the database

• @default

      attribute @default(_ value: ContextType)
  

  Defines a default value for a field.

  Params:

  Name	Description
  value	The default value expression

• @unique

      attribute @unique(map: String?)
  

  Defines a unique constraint for this field.

  Params:

  Name	Description
  map	The name of the underlying primary key constraint in the database

• @relation

      attribute @relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?, map: String?)
  

  Defines meta information about a relation.

  Params:

  Name	Description
  name	The name of the relationship
  fields	A list of fields defined in the current model
  references	A list of fields of the model on the other side of the relation
  onDelete	Referential action to take on delete. See details here.
  onUpdate	Referential action to take on update. See details here.

• @map

      attribute @map(_ name: String)
  

  Maps a field name or enum value from the schema to a column with a different name in the database.

  Params:

  Name	Description
  map	The name of the underlying column in the database

• @updatedAt

      attribute @updatedAt()
  

  Automatically stores the time when a record was last updated.

• @password

      attribute @password(saltLength: Int?, salt: String?)
  

  Indicates that the field is a password field and needs to be hashed before persistence.

  NOTE: ZenStack uses bcryptjs library to hash password. You can use the saltLength parameter to configure the cost of hashing, or use salt parameter to provide an explicit salt. By default, salt length of 12 is used. See bcryptjs for more details.

  Params:

  Name	Description
  saltLength	The length of salt to use (cost factor for the hash function)
  salt	The salt to use (a pregenerated valid salt)

• @omit

      attribute @omit()
  

  Indicates that the field should be omitted when read from the generated services. Commonly used together with @password attribute.

Model attributes

• @@unique

      attribute @@unique(_ fields: FieldReference[], name: String?, map: String?)
  

  Defines a compound unique constraint for the specified fields.

  Params:

  Name	Description
  fields	A list of fields defined in the current model
  name	The name of the unique combination of fields
  map	The name of the underlying unique constraint in the database

• @@index

      attribute @@index(_ fields: FieldReference[], map: String?)
  

  Defines an index in the database.

  Params:

  Name	Description
  fields	A list of fields defined in the current model
  map	The name of the underlying index in the database

• @@map

      attribute @@map(_ name: String)
  

  Maps the schema model name to a table with a different name, or an enum name to a different underlying enum in the database.

  Params:

  Name	Description
  name	The name of the underlying table or enum in the database

• @@allow

      attribute @@allow(_ operation: String, _ condition: Boolean)
  

  Defines an access policy that allows a set of operations when the given condition is true.

  Params:

  Name	Description
  operation	Comma separated list of operations to control, including "create", "read", "update", and "delete". Pass "all" as an abbriviation for including all operations.
  condition	Boolean expression indicating if the operations should be allowed

• @@deny

      attribute @@deny(_ operation: String, _ condition: Boolean)
  

  Defines an access policy that denies a set of operations when the given condition is true.

  Params:

  Name	Description
  operation	Comma separated list of operations to control, including "create", "read", "update", and "delete". Pass "all" as an abbriviation for including all operations.
  condition	Boolean expression indicating if the operations should be denied

Predefined attribute functions

• uuid

      function uuid(): String {}
  

  Generates a globally unique identifier based on the UUID spec.

• cuid

      function cuid(): String {}
  

  Generates a globally unique identifier based on the CUID spec.

• now

      function now(): DateTime {}
  

  Gets current date-time.

• autoincrement

      function autoincrement(): Int {}
  

  Creates a sequence of integers in the underlying database and assign the incremented values to the ID values of the created records based on the sequence.

• dbgenerated

      function dbgenerated(expr: String): Any {}
  

  Represents default values that cannot be expressed in the Prisma schema (such as random()).

• auth

      function auth(): User {}
  

  Gets the current login user. The return type of the function is the User data model defined in the current ZModel.

Examples

Here're some examples on using field and model attributes:

model User {
    // unique id field with a default UUID value
    id String @id @default(uuid())

    // require email field to be unique
    email String @unique

    // password is hashed with bcrypt with length of 16, omitted when returned from the CRUD services
    password String @password(saltLength: 16) @omit

    // default to current date-time
    createdAt DateTime @default(now())

    // auto-updated when the entity is modified
    updatedAt DateTime @updatedAt

    // mapping to a different column name in database
    description String @map("desc")

    // mapping to a different table name in database
    @@map("users")

    // use @@index to specify fields to create database index for
    @@index([email])
}