Timestamps

Ormed provides automatic timestamp management for created_at and updated_at columns.

Enabling Timestamps

Add the Timestamps marker mixin to your model:

@OrmModel(table: 'posts')
class TimestampPost extends Model<TimestampPost> with Timestamps {
  const TimestampPost({required this.id, required this.title});

  @OrmField(isPrimaryKey: true, autoIncrement: true)
  final int id;

  final String title;
}

The code generator detects this mixin and:

• Adds virtual createdAt and updatedAt fields if not explicitly defined
• Applies timestamp implementation to the generated tracked class
• Automatically sets timestamps on insert/update operations

Carbon Integration

Ormed integrates with the Carbonized library to provide a fluent API for date manipulation. The createdAt and updatedAt getters return a CarbonInterface? instance.

final user = await repo.find(1);
if (user != null) {
  print(user.createdAt?.diffForHumans()); // "2 hours ago"
  print(user.updatedAt?.addDays(1).isFuture); // true
}

Timestamps are Immutable

Ormed returns immutable Carbon instances from timestamp getters. This means you can safely chain methods like subDay() without accidentally mutating the model's state:

final yesterday = user.createdAt?.subDay(); // Safe! Returns new instance
print(user.createdAt); // Original value unchanged

See the Date and Time Handling guide for more details on mutable vs immutable Carbon behavior.

Flexible Setters

The createdAt and updatedAt setters accept both standard Dart DateTime objects and CarbonInterface instances.

user.updatedAt = DateTime.now();
// or
user.updatedAt = Carbon.now().subDays(1);

Timezone-Aware Timestamps

For timestamps stored in UTC, use TimestampsTZ:

@OrmModel(table: 'articles')
class TimestampArticleTz extends Model<TimestampArticleTz> with TimestampsTZ {
  const TimestampArticleTz({required this.id, required this.title});

  @OrmField(isPrimaryKey: true, autoIncrement: true)
  final int id;

  final String title;
}

This ensures:

• All timestamps are converted to UTC before storage
• Timestamps remain in UTC when retrieved
• Your application handles timezone conversion for display

Migration Setup

Add timestamp columns in your migration:

Notes

If you use Timestamps/TimestampsTZ, keep the schema column names aligned with your model configuration.

Code

class AddTimestampsToPosts extends Migration {
  const AddTimestampsToPosts();

  @override
  void up(SchemaBuilder schema) {
    schema.table('posts', (table) {
      // Non-timezone aware (stored as-is)
      table.timestamps();

      // OR timezone aware (UTC storage)
      // table.timestampsTz();

      // OR nullable timestamps
      // table.nullableTimestamps();
      // table.nullableTimestampsTz();
    });
  }

  @override
  void down(SchemaBuilder schema) {
    schema.table('posts', (table) {
      table.dropColumn('created_at');
      table.dropColumn('updated_at');
    });
  }
}

Custom Column Names

By default, Ormed uses created_at and updated_at. These can be customized via model configuration if needed.

Behavior

On Insert

• created_at is set to the current timestamp
• updated_at is set to the current timestamp

On Update

• updated_at is automatically updated
• created_at remains unchanged

Manual Control

You can manually set timestamps if needed:

// You can manually set timestamps using DateTime or Carbon:
// final post = $TimestampPost(
//   id: 0,
//   title: 'My Post',
//   createdAt: DateTime(2024, 1, 1),
//   updatedAt: Carbon.now().subDays(1),
// );

Without Timestamps

If you don't need automatic timestamps, simply don't include the mixin:

@OrmModel(table: 'logs')
class Log extends Model<Log> {
  // No timestamps mixin - manual control
  const Log({required this.id, required this.message, this.timestamp});

  @OrmField(isPrimaryKey: true)
  final int id;

  final String message;
  final DateTime? timestamp;
}