add support for default column values

Author: schultek

CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+
+- Added support for default column values via the `@Default` annotation.
+
 # 0.17.0
 
 - Require dart sdk `>=3.7.0`.

doc/models.md

@@ -41,6 +41,41 @@ abstract class Book {
 }
 ```
 
+## Default Values
+
+You can specify a SQL default value for a model field using the `@Default()` annotation.
+The annotation takes a raw SQL expression string which will be emitted verbatim into the generated `CREATE TABLE` statement.
+
+```dart
+@Model()
+abstract class Book {
+  @PrimaryKey()
+  String get id;
+
+  // string default (note the single quotes are part of the value)
+  @Default("'untitled'")
+  String get title;
+
+  // numeric default (no quotes)
+  @Default('0')
+  int get pageCount;
+
+  // datetime default using the provided convenience constructor
+  @Default.currentTimestamp()
+  DateTime get createdAt;
+}
+```
+
+When inserting a new value, any property that is not provided will be set to the default value.
+
+```dart
+db.books.insertOne(BookInsertRequest(
+  id: 'book0' 
+  // title, pageCount and createdAt are optional and 
+  // will be set to their default values if not provided
+));
+```
+
 ## Relations
 
 When using relational database systems, you model your data using relations, namely one-to-one,

example/lib/database.schema.dart

@@ -12,6 +12,9 @@ abstract class Invoice {
   String get title;
   String get invoiceId;
 
+  @Default.currentTimestamp()
+  DateTime get createdAt;
+
   @HiddenIn(#Owner)
   Account? get account;
 

example/lib/models/invoice.dart

@@ -14,6 +14,7 @@ abstract mixin class NamedColumnElement implements ParameterColumnElement {
   bool get isNullable;
   String get sqlType;
   String get rawSqlType;
+  String? get defaultValue;
 }
 
 mixin RelationalColumnElement implements ColumnElement {

example/lib/models/invoice.schema.dart

@@ -15,6 +15,9 @@ class FieldColumnElement extends ColumnElement with NamedColumnElement {
 
   late final bool isAutoIncrement;
 
+  @override
+  late final String? defaultValue;
+
   FieldColumnElement(this.parameter, TableElement parentTable, BuilderState state)
     : super(parentTable, state) {
     isAutoIncrement =
@@ -34,6 +37,16 @@ class FieldColumnElement extends ColumnElement with NamedColumnElement {
       throw 'Column field was annotated with "${r.toSource()}", which is not supported.\n'
           '  - ${parameter.displayString()}';
     }
+
+    final defaultAnnotation =
+        defaultChecker.firstAnnotationOf(parameter) ??
+        defaultChecker.firstAnnotationOf(getter ?? parameter);
+    if (defaultAnnotation != null) {
+      var r = ConstantReader(defaultAnnotation);
+      defaultValue = r.read('value').stringValue;
+    } else {
+      defaultValue = null;
+    }
   }
 
   @override

lib/src/builder/elements/column/column_element.dart

@@ -50,4 +50,7 @@ class ForeignColumnElement extends ColumnElement
       return true;
     }
   }
+
+  @override
+  String? get defaultValue => null;
 }

lib/src/builder/elements/column/field_column_element.dart

@@ -87,10 +87,14 @@ class InsertGenerator {
 
     String toInsertValue(NamedColumnElement e) {
       final converter = e.converter;
-      if (converter != null) {
-        return '\${values.add(${converter.toSource()}.tryEncode(r.${e.paramName}))}:${e.rawSqlType}';
+      final value =
+          converter != null
+              ? '\${values.add(${converter.toSource()}.tryEncode(r.${e.paramName}))}:${e.rawSqlType}'
+              : '\${values.add(r.${e.paramName})}:${e.rawSqlType}';
+      if (e.defaultValue != null) {
+        return '\${r.${e.paramName} != null ? \'$value\' : \'DEFAULT\'}';
       } else {
-        return '\${values.add(r.${e.paramName})}:${e.rawSqlType}';
+        return value;
       }
     }
 
@@ -121,7 +125,8 @@ class InsertGenerator {
         if (!column.isAutoIncrement) {
           requestFields.add(
             MapEntry(
-              column.parameter.type.getDisplayString(withNullability: true),
+              column.parameter.type.getDisplayString(withNullability: false) +
+                  (column.isNullable || column.defaultValue != null ? '?' : ''),
               column.paramName,
             ),
           );

lib/src/builder/elements/column/foreign_column_element.dart

@@ -8,7 +8,11 @@ class TableJsonGenerator {
       'columns': {
         for (var column in table.columns)
           if (column is NamedColumnElement)
-            column.columnName: {'type': column.sqlType, if (column.isNullable) 'isNullable': true},
+            column.columnName: {
+              'type': column.sqlType,
+              if (column.isNullable) 'isNullable': true,
+              if (column.defaultValue case String v) 'default': v,
+            },
       },
       'constraints': [
         if (table.primaryKeyColumn != null)