schema library Declare models

Declares models and tables together using typed Record column declarations.

Import this library in a schema source; generate its immutable rows, typed queries and physical snapshot with dart run orm generate lib/schema.dart. Declaration callbacks and application factories are not executed by generation.

import 'package:orm/schema.dart';

final user = model('users', (
  id: identity(),
  email: text(unique: true),
  name: text().nullable(),
));

Use the generated client for queries, schema_model.dart for physical metadata, and migrate.dart for reviewed database changes.

Classes

CheckDefinition

A trusted database CHECK declaration for the checks argument of model.

Codec<T>

Converts a typed Dart value to database storage and decodes it on reads.

Codecs

Built-in conversions for SQL scalar values, JSON, and exact numeric types.

ColumnDefinition<T>

Typed source syntax for a stored column, interpreted by static generation.

Decimal

A finite base-ten value, independent of binary floating point.

IndexDefinition

An index declaration for the indexes selector of model.

LocalDate

A Gregorian calendar date, without a time or timezone. Year 0 is 1 BC; negative years use astronomical numbering.

LocalDateTime

Calendar date and wall-clock time, with no timezone or implied UTC instant.

LocalTime

A wall-clock time at microsecond resolution, including the endpoint 24:00. The fourth constructor argument is the full fractional second (0..999999).

Model

One source definition for a physical table and its generated immutable row.

ReferenceDefinition

A relationship in the named Record returned by the relations selector of model. Its Record field name becomes the generated query navigation name.

SqlDeclaration

Source metadata for a typed SQL query, created through sqlQuery.

SqlJson

A non-SQL-null JSON document. Its value may itself be JSON null. Drivers use this envelope for parsed JSON, including JSON string scalars.

SqlReal

Explicit floating-point SQL input. JavaScript cannot distinguish an integral double from int by runtime type; this preserves the SQL intention.

Enums

ComputedStorage

How a database maintains a computed column, subject to engine capabilities.

DecimalRounding

Rounding is explicit; exact rejects a non-zero discarded remainder.

ReferentialAction

Database behavior when a referenced row is deleted.

Extensions

InstantPrecision on DateTime

Explicit precision conversion for resolved UTC instants.

Functions

bigInteger({String? name, bool unique = false, String? defaultSql, BigInt clientDefault()?}) → ColumnDefinition<BigInt>

An exact large integer column.

boolean({String? name, bool unique = false, bool? defaultValue, String? defaultSql, bool clientDefault()?}) → ColumnDefinition<bool>

A boolean column.

bytes({String? name, bool unique = false, String? defaultSql, Uint8List clientDefault()?}) → ColumnDefinition<Uint8List>

A binary column.

check(String expression, {required String? name, String? sqlite, String? postgres, String? mysql, String? mariadb}) → CheckDefinition

Declares a CHECK using physical column names. The database evaluates the trusted SQL expression. Dialect overrides are explicit. Use a stable name, or name: null to preserve an unnamed imported constraint.

custom<T>(Codec<T> codec, {String? name, bool unique = false, String? defaultSql, T clientDefault()?, int? bits, int? precision, int? scale}) → ColumnDefinition<T>

A domain value with a public const codec. Generation reads its storage tag and references its encode/decode functions without executing them. bits constrains integer storage to 16, 32 or 64 bits. precision and scale configure decimal storage; temporal storage accepts precision from 0 to 6. These options describe storage, independently of the Dart type.

date({String? name, bool unique = false, String? defaultSql, LocalDate clientDefault()?}) → ColumnDefinition<LocalDate>

A calendar date without a timezone.

dateTime({String? name, bool unique = false, String? defaultSql, DateTime clientDefault()?, int? precision}) → ColumnDefinition<DateTime>

A UTC instant column.

decimal({String? name, bool unique = false, String? defaultSql, Decimal clientDefault()?, int? precision, int? scale}) → ColumnDefinition<Decimal>

An exact decimal column.

enumeration<E extends Enum>(List<E> values, {String? name, bool unique = false, Map<E, String>? labels, E? defaultValue, String? defaultSql, E clientDefault()?}) → ColumnDefinition<E>

An enum stored as text. Pass Status.values; optional labels maps every constant to a distinct stable storage label without annotations. defaultValue is encoded into a database default during generation.

identity({String? name}) → ColumnDefinition<int>

A generated integer primary key. It may not be nullable or part of a composite key. Omitted insert values are supplied by the database.

index(Object columns, {required String name, bool unique = false}) → IndexDefinition

Selects a direct column or an ordered positional Record of columns. The physical name is explicit and does not depend on local variable names.

integer({String? name, bool unique = false, int? defaultValue, String? defaultSql, int clientDefault()?, int? bits}) → ColumnDefinition<int>

A signed integer column.

json({String? name, bool unique = false, String? defaultSql, SqlJson clientDefault()?}) → ColumnDefinition<SqlJson>

A JSON document; its content can itself be JSON null.

localDateTime({String? name, bool unique = false, String? defaultSql, LocalDateTime clientDefault()?, int? precision}) → ColumnDefinition<LocalDateTime>

A local timestamp without a timezone.

model<S extends Record>(String table, S fields, {Object primaryKey(S)?, List<Object> uniqueKeys(S)?, List<IndexDefinition> indexes(S)?, Record relations(S)?, List<CheckDefinition>? checks}) → Model

Defines a model using named column declarations and local constraints.

real({String? name, bool unique = false, double? defaultValue, String? defaultSql, double clientDefault()?}) → ColumnDefinition<double>

A floating-point column.

referencedBy(Model target(), {Record? on}) → ReferenceDefinition

Declares reverse navigation on the current model, without another foreign key.

references(Object columns, Model target(), {ReferentialAction onDelete = ReferentialAction.restrict, bool constraint = true}) → ReferenceDefinition

Declares a foreign key and forward navigation on the current model.

sqlQuery({required Record result, Record parameters = (), String? sqlite, String? postgres, String? mysql, String? mariadb}) → SqlDeclaration

A fixed SQL file with named result and parameter column declarations.

text({String? name, bool unique = false, String? defaultValue, String? defaultSql, String clientDefault()?}) → ColumnDefinition<String>

A text column.

time({String? name, bool unique = false, String? defaultSql, LocalTime clientDefault()?, int? precision}) → ColumnDefinition<LocalTime>

A wall-clock time without a timezone.

Exceptions / Errors

OrmException

An ORM failure with a stable machine-readable code and optional cause.