Types, Enums, And Embedded Types

Scalar Types

Type	PostgreSQL	Notes
`string`	`text`	Use `@maxLength(n)` instead of varchar
`int`	`integer`
`smallint`	`smallint`
`bigint`	`bigint`
`decimal(p, s)`	`numeric(p, s)`	Precision and scale required
`double`	`double precision`
`boolean`	`boolean`
`datetime`	`timestamptz`	Always with timezone
`date`	`date`
`uuid`	`uuid`	Default primary key type
`bytes`	`bytea`
`json`	`jsonb`	Untyped; prefer embedded types when shape is known
`file`	`jsonb`	File metadata; see Files And Network

Nullable, Default, And Array

entity Example {
  required: string,            // required by default
  optional: string?,           // nullable with ?
  withDefault: boolean = false, // inline default value
  tags: string[],              // array type with []
  scores: int[],
}

Arrays of embedded types and json compile to jsonb. Nested arrays (type[][]) are not supported.

Field Annotations

Constraints

Annotation	Description
`@unique`	UNIQUE constraint on the column
`@primaryKey`	Use as the primary key
`@onDelete(cascade\|restrict\|setNull)`	FK delete behavior

String Validation

Annotation	Description
`@minLength(n)`	Minimum character count
`@maxLength(n)`	Maximum character count
`@regex("pattern")`	Must match regex
`@email`	Must be valid email format
`@url`	Must be valid URL format
`@trim`	Strip leading/trailing whitespace before saving

Numeric Validation

Annotation	Description
`@min(n)`	Minimum value
`@max(n)`	Maximum value

File Validation

Annotation	Description
`@maxSize(n)`	Maximum file size in bytes. Rejected at upload time if the declared size exceeds this limit.
`@accept("mime/types")`	Comma-separated MIME type patterns. Supports wildcards (e.g., `"image/*,application/pdf"`). Rejected at upload time if the MIME type does not match.

Valid only on file fields. Enforced when a presigned upload URL is requested.

Data Protection

Annotation	Description
`@sensitive`	Application-level encryption at rest (AES-256-GCM)
`@pii`	Personally identifiable information — values are replaced with `[PII:field_name]` in structured logs. Log safety only, not encryption. Use `@sensitive` for encryption at rest.
`@index(equality)`	HMAC blind index for exact-match queries on `@sensitive` fields

Validation annotations (@minLength, @maxLength, @min, @max, @regex, @email, @url, @maxSize, @accept) are enforced on every insert, update, or file upload request.

Other

Annotation	Description
`@index`	Create a B-tree index on the column

Entity-Level Annotations

These appear inside the entity body but apply to the entity as a whole.

Annotation	Description
`@unique([f1, f2])`	Composite unique constraint
`@index([f1, f2])`	Composite index
`@primaryKey([f1, f2])`	Composite primary key
`@suppress([W0001])`	Suppress specific compiler warnings
`@system`	Marks as a system-managed entity
`@noDefaults`	Exclude from the `defaults {}` block

Enums

An enum defines a closed set of named values. The compiler generates a PostgreSQL ENUM type.

enum ProjectStatus {
  Draft,
  Active,
  Archived,
}

enum TeamRole {
  Member,
  Admin,
  Owner,
}

Use enum names as field types:

entity Project {
  status: ProjectStatus,
  archivedAt: datetime?,
}

Use enum values in policy conditions:

entity Project {
  status: ProjectStatus,

  @grant read to @public where resource.status == Active
}

Embedded Types

An embedded type declares a typed shape stored as a jsonb column. Embedded types have no separate table, no id, no created_at/updated_at, no policies, and no foreign keys.

embedded type Address {
  street: string,
  city: string,
  state: string @maxLength(2),
  zip: string,
  country: string = "US",
}

embedded type Preferences {
  theme: string = "light",
  notifications: boolean = true,
}

Use embedded types as field types on entities:

entity User {
  name: string,
  address: Address?,
  preferences: Preferences = Preferences{},
  shippingAddresses: Address[],
}

Preferences = Preferences{} defaults to a JSONB object with all field defaults filled in. Embedded types can be nested and used in arrays.

Use embedded types for value objects with no independent identity — addresses, settings, metadata blobs. Use entities when you need id, policies, or relations.

Related guides: Build Your First App, Authorization

Types, Enums, And Embedded Types

On this page