Documentation for @DefaultValue (#305)

Author: jonasfj

typed_sql/doc/01_schema.md

@@ -15,7 +15,7 @@ We must then define a _schema class_. This is an `abstract final class`
 extending [Schema], specifying what tables the database has.
 If we were working on a bookstore we might define a schema as follows:
 
-```dart schema_test.dart#schema
+```dart schema_references_test.dart#schema
 abstract final class Bookstore extends Schema {
   Table<Author> get authors;
   Table<Book> get books;
@@ -37,7 +37,7 @@ For each table in our database we must define a _row class_. This is an
 the database table has. Continuing with the bookstore example we can define a
 _row class_ for the `authors` table as follows:
 
-```dart schema_test.dart#author-model
+```dart schema_references_test.dart#author-model
 @PrimaryKey(['authorId'])
 abstract final class Author extends Row {
   @AutoIncrement()
@@ -95,7 +95,7 @@ _row class_ for the `books` table in the `Bookstore` schema. If we want the
 `books` table to have a _foreign key_ referencing the `authors` table we can
 define the `Book` _row class_ as follows:
 
-```dart schema_test.dart#book-model
+```dart schema_references_test.dart#book-model
 @PrimaryKey(['bookId'])
 abstract final class Book extends Row {
   @AutoIncrement()
@@ -123,9 +123,6 @@ abstract final class Book extends Row {
 }
 ```
 
-The `@DefautValue(0)` annotation gives the `stock` field a default value of `0`.
-This also makes the `stock` field optional when inserting rows.
-
 > [!NOTE]
 > The `name` and `as` properties in the `@References` annotation are optional.
 > These gives rise to convinient subquery properties we can use when writing
@@ -145,6 +142,53 @@ CREATE TABLE books (
 Notice that because the `title` field is nullable, it does not have a `NOT NULL`
 constraint in the database.
 
+## Adding a default value
+In our bookstore example above, the _row class_ `Book` has a `stock` field
+annotated with `@DefaultValue(0)`. This gives the `stock` field a default value
+of `0`, and thus, causes the `stock` field to be optional when inserting rows.
+
+```dart schema_default_value_test.dart#book-model
+@PrimaryKey(['bookId'])
+abstract final class Book extends Row {
+  @AutoIncrement()
+  int get bookId;
+
+  String? get title;
+
+  @References(table: 'authors', field: 'authorId', name: 'author', as: 'books')
+  int get authorId;
+
+  @DefaultValue(0) // Gives the `stock` field to have a default value!
+  int get stock;
+}
+```
+
+The equivalent SQL depends on the database, but it looks something like:
+```sql
+CREATE TABLE books (
+  bookId BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  title TEXT,
+  authorId BIGINT NOT NULL,
+  stock BIGINT NOT NULL DEFAULT 0,
+  FOREIGN KEY (authorId) REFERENCES authors (authorId)
+);
+```
+
+Notice the `DEFAULT 0` clause in the declaration of the `stock` field.
+
+It is possible to define default values for `String`, `bool`, `int` and `double`
+fields, using the `@DefaultValue(...)` annotation. However, since [DateTime]
+does not have a _const_ constructor one of the following annoations must be
+used to create a [DateTime] field with a _default value_:
+ * `@DefaultValue.dateTime(year, [month, day, ...])`,
+ * `@DefaultValue.epoch`, or,
+ * `@DefaultValue.now`.
+
+With [DefaultValue.now] being a special constructor that uses
+`CURRENT_TIMESTAMP` in the database to ensure the field
+has a default value of `DateTime.now().toUtc()` when row is inserted.
+
+See [DefaultValue] for further documentation on _default values_.
 
 ## Generating code
 Whenever the definition of the database schema is changed, it's important to
@@ -177,7 +221,7 @@ your database, as well as how you are connecting.
 
 Once you have `Database<Bookstore>` instance you can create empty tables for
 your schema as follows:
-```dart schema_test.dart#create-tables
+```dart schema_references_test.dart#create-tables
 // Create tables
 await db.createTables();
 ```
@@ -186,7 +230,7 @@ Creating empty tables from scratch is mostly useful for testing, it's rarely
 needed in production. Instead you can use the generated `create<Schema>Tables`,
 which outputs the [DDL] for creating the tables.
 
-```dart schema_test.dart#get-ddl
+```dart schema_references_test.dart#get-ddl
 // Get the database schema
 final ddl = createBookstoreTables(SqlDialect.postgres());
 ```
@@ -204,7 +248,7 @@ database migrations. See [Migrations documentation][Migrations].
 With a `Database<Bookstore>` and tables created through migrations or
 `db.createTables()` you can insert data into the database as follows:
 
-```dart schema_test.dart#insert-data
+```dart schema_references_test.dart#insert-data
 // Insert a row into the "authors" table
 final author = await db.authors
     .insert(
@@ -226,7 +270,7 @@ Now we can also write queries against the database. The following demonstrates
 how to write a query that filters on the book title and only returns `title`
 and `author.name`.
 
-```dart schema_test.dart#query-data
+```dart schema_references_test.dart#query-data
 // Query for books where the title contains 'eggs'
 // select the title and author name
 final titleAndAuthor = await db.books

typed_sql/doc/03_writing_queries.md

@@ -605,7 +605,7 @@ Recall that `Author.name` is annotated with `@Unique()`. This means that the
 _name_ field in the database will have `UNIQUE` constraint. But also that
 `Query<(Expr<Author>,)>` will have a convenient `.byName` method.
 
-```dart schema_test.dart#author-model
+```dart schema_references_test.dart#author-model
 @PrimaryKey(['authorId'])
 abstract final class Author extends Row {
   @AutoIncrement()

typed_sql/doc/05_foreign_keys.md

@@ -59,7 +59,7 @@ these point to the _table_ and _field_ that is being referenced.
 The `name` and `as` properties are optional, if present they will be used to
 generate convenient subquery properties when building queries.
 
-```dart schema_test.dart#book-model
+```dart schema_references_test.dart#book-model
 @PrimaryKey(['bookId'])
 abstract final class Book extends Row {
   @AutoIncrement()

typed_sql/lib/src/typed_sql.annotations.dart

@@ -23,7 +23,10 @@ final class PrimaryKey {
   const PrimaryKey(this.fields);
 }
 
-/// Annotation for a field that has a default value.
+/// Annotation that assigns a _default value_ to a field.
+///
+/// Using this annotation on a non-nullable field, also causes the field
+/// to be _optional_ when inserting rows.
 ///
 /// {@category schema}
 final class DefaultValue {
@@ -39,7 +42,25 @@ final class DefaultValue {
   const DefaultValue._(String kind, Object value)
       : _value = (kind: kind, value: value);
 
+  /// Annotate a field with a constant default value.
+  ///
+  /// The [value] must be one of the following types:
+  ///  * [String],
+  ///  * [bool],
+  ///  * [int], or,
+  ///  * [double].
+  ///
+  /// Consequently, this constructor can only be used to annotate a
+  /// _default value_ to a field of a matching type.
   const DefaultValue(Object value) : _value = (kind: 'raw', value: value);
+
+  /// Annotate a [DateTime] field with a fixed default value.
+  ///
+  /// This constructor behaves similar to [DateTime.utc], as arguments will all
+  /// be interpreted as UTC.
+  ///
+  /// To use `CURRENT_TIMESTAMP` as default value for a field, see
+  /// [DefaultValue.now].
   const DefaultValue.dateTime(
     int year, [
     int month = 1,
@@ -63,7 +84,16 @@ final class DefaultValue {
           ),
         );
 
+  /// Annotate a [DateTime] field with a default value of
+  /// `1970-01-01T00:00:00Z`.
   static const DefaultValue epoch = DefaultValue._('datetime', 'epoch');
+
+  /// Annotate a [DateTime] field with a default value of `CURRENT_TIMESTAMP`.
+  ///
+  /// This will cause the field to have a default value of the current timestamp
+  /// in UTC, when a row is inserted.
+  ///
+  /// See [Expr.currentTimestamp] for further details.
   static const DefaultValue now = DefaultValue._('datetime', 'now');
 }
 

typed_sql/test/typed_sql/example/bookstore/bookstore_test.dart

@@ -21,10 +21,11 @@ import '../../testrunner.dart';
 
 part 'bookstore_test.g.dart';
 
-// Remark: please keep this schema in sync with ../schema/schema_test.dart
+// Remark: please keep this schema in sync with ../schema/**_test.dart
 //         Documentation will assume that both of them uses the same schema,
-//         we just have different clips of the regions, and schema_test.dart
-//         has more comments.
+//         we just have different clips of the regions and comments in:
+//         - schema_default_value_test.dart
+//         - schema_references_test.dart
 
 // #region bookstore-schema
 abstract final class Bookstore extends Schema {

typed_sql/test/typed_sql/example/schema/schema_default_value/schema_default_value_test.dart

@@ -0,0 +1,71 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'package:typed_sql/typed_sql.dart';
+
+import '../../../testrunner.dart';
+
+part 'schema_default_value_test.g.dart';
+
+// Remark: please keep this schema in sync with ../bookstore/bookstore_test.dart
+//         Documentation will assume that both of them uses the same schema,
+//         we just have different clips of the regions and comments in:
+//         - schema_default_value_test.dart
+//         - schema_references_test.dart
+
+abstract final class Bookstore extends Schema {
+  Table<Author> get authors;
+  Table<Book> get books;
+}
+
+@PrimaryKey(['authorId'])
+abstract final class Author extends Row {
+  @AutoIncrement()
+  int get authorId;
+
+  @Unique()
+  @SqlOverride(dialect: 'mysql', columnType: 'VARCHAR(255)') // #hide
+  String get name;
+}
+
+// #region book-model
+@PrimaryKey(['bookId'])
+abstract final class Book extends Row {
+  @AutoIncrement()
+  int get bookId;
+
+  String? get title;
+
+  @References(table: 'authors', field: 'authorId', name: 'author', as: 'books')
+  int get authorId;
+
+  @DefaultValue(0) // Gives the `stock` field to have a default value!
+  int get stock;
+}
+// #endregion
+
+void main() {
+  final r = TestRunner<Bookstore>();
+
+  r.addTest('use the database', (db) async {
+    // Create tables
+    await db.createTables();
+
+    // Get the database schema
+    final ddl = createBookstoreTables(SqlDialect.postgres());
+    check(ddl).isNotEmpty();
+  });
+
+  r.run();
+}