create method

Future<TChild> create(TChild child, { Map<String, Object?> pivot = const <String, Object?>{}, })

Inserts child with this parent's key written onto the foreign key.

belongsTo is associate, not create: the foreign key lives on the parent. hasOneThrough / hasManyThrough have no owned write surface. A belongs-to-many insert stores the child and the pivot in one transaction so a failed link does not leave an orphan row the caller never asked to keep.

Implementation

Future<TChild> create(
  TChild child, {
  Map<String, Object?> pivot = const <String, Object?>{},
}) {
  switch (relation.kind) {
    case MssqlRelationKind.hasOne:
    case MssqlRelationKind.hasMany:
    case MssqlRelationKind.morphOne:
    case MssqlRelationKind.morphMany:
      return _insertChild(child);
    case MssqlRelationKind.belongsToMany:
    case MssqlRelationKind.morphToMany:
      return _transact((s) async {
        final written = await copy(s)._insertChild(child);
        await copy(s)._attachRow(written, pivot);
        return written;
      });
    case MssqlRelationKind.belongsTo:
    case MssqlRelationKind.morphTo:
      throw StateError(
        'create() on "${relation.name}" is ${relation.kind.name}: the '
        'foreign key lives on ${parentBinding.qualifiedName}. Call '
        'associate() for an existing counterpart, or insert the child '
        'table directly.',
      );
    case MssqlRelationKind.hasOneThrough:
    case MssqlRelationKind.hasManyThrough:
      throw StateError(
        'create() on "${relation.name}" is ${relation.kind.name}: there '
        'is no owned foreign key or declared pivot to write. Insert the '
        'intermediate row yourself.',
      );
  }
}