Driver Overrides

Some databases differ in their best column types (and sometimes their best codecs) for the same Dart field. Ormed supports expressing those differences on a per-field basis with @OrmField(driverOverrides: ...).

This is useful when:

• A field should be jsonb on PostgreSQL, but TEXT on SQLite.
• One driver returns JSON values as a Map, while another returns a JSON string (and needs a different codec).

Field overrides (driverOverrides)

Define per-driver overrides keyed by the driver name (lowercased):

@OrmModel(table: 'driver_override_examples')
class DriverOverrideExample extends Model<DriverOverrideExample> {
  const DriverOverrideExample({required this.id, required this.payload});

  @OrmField(isPrimaryKey: true)
  final int id;

  @OrmField(
    columnType: 'TEXT',
    driverOverrides: {
      'postgres': OrmDriverFieldOverride(
        columnType: 'jsonb',
        codec: PostgresPayloadCodec,
      ),
      'sqlite': OrmDriverFieldOverride(
        columnType: 'TEXT',
        codec: SqlitePayloadCodec,
      ),
    },
  )
  final Map<String, Object?> payload;
}

Notes:

• Keys are normalized (trimmed + lowercased) before matching.
• Keys should match driver.metadata.name (for example: sqlite, postgres, mysql, mariadb).
• Overrides can change columnType, defaultValueSql, and codec.

Model driver annotations (driverAnnotations)

@OrmModel(driverAnnotations: [...]) attaches marker annotations to the generated model definition. A driver can use these to opt into custom hooks or behavior for a subset of models.

@OrmModel(table: 'audited_events', driverAnnotations: ['audited'])
class AuditedEvent extends Model<AuditedEvent> {
  const AuditedEvent({required this.id, required this.action});

  @OrmField(isPrimaryKey: true)
  final int id;

  final String action;
}

Related

• For migration-time overrides, see Migrations → Schema Builder → Driver-Specific Overrides.
• For value transforms that do not depend on a driver, see Models → Casting.