No documentation of failure states (or it is hard to find if it exists?)

[SRNissen]

It is not clear from the documentation, nor from the code comments, nor from the actual code, what happens in several cases.

The comment from InsertAsync, as seen in SqlMapperExentsions.Async.cs

    /// <summary>
    /// Inserts an entity into table "Ts" asynchronously using Task and returns identity id.
    /// </summary>
    /// <typeparam name="T">The type being inserted.</typeparam>
    /// <param name="connection">Open SqlConnection</param>
    /// <param name="entityToInsert">Entity to insert</param>
    /// <param name="transaction">The transaction to run under, null (the default) if none</param>
    /// <param name="commandTimeout">Number of seconds before command execution timeout</param>
    /// <param name="sqlAdapter">The specific ISqlAdapter to use, auto-detected based on connection if null</param>
    /// <returns>Identity of inserted entity</returns>

Steps to reproduce:

• First, read https://github.com/DapperLib/Dapper.Contrib/blob/main/docs/index.md
• Next, read https://github.com/DapperLib/Dapper.Contrib/blob/main/Readme.md

Expected outcome:

Learn how to handle edge cases that might be encountered when using Dapper.Contrib

Actual outcome:

I currently lack clarity on the following:

1. InsertAsync, return value when Task<int> cannot represent key in database

   • What is the "Identity" returned when the table uses long and has more than INTMAX entities? [1]
   • What is the "Identity" returned when the key is a GUID or hashed string?
   • What is the "Identity" returned after inserting an IEnumerable<Entity>?

2. InsertAsync, single entity, non-zero key in key-incrementing table

   • Insert nothing and return zero?
   • Insert nothing and throw?
     • If so, what?
     • Insert entity as if the key was zero, return the key of the new row?
   • Behavior depends on underlying database?

3. InsertAsync, single entity, non-zero key already in table

   • Retain existing entity and return zero?
   • Retain existing entity and throw exception?
     • If so, which one?
   • Insert entity as if the key was zero, return the key of the new row?
   • Retain existing entity, returning its key?
     • If so, any way to learn you didn't insert?
   • Overwrite existing entity, returning the key?
   • Behavior depends on underlying database?

4. InsertAsync, multiple entities, some keys already in table

   • Insert none and return zero?
   • Insert none and throw exception?
     • If so, which one?
   • Insert new entities only and retain existing entities, returning count of delta?
     • if so - any way to learn which ones were not inserted?
   • Insert all, overwriting existing entities, returning count of all entities in original list?
   • Behavior depends on underlying database?

5. InsertAsync, single or multiple insert, table not found
   (The entity class name does not correspond to any table names, the [Table("name")] attribute is not present)

   • Return zero?
   • Throw exception?
     • If so, which exception?
   • Wildcard option: Create that table and populate it?
   • Behavior depends on underlying database?

6. InsertAsync, single or multiple insert, column not found
   (Entity has field that is not marked [Write(false)], column does not exist in database)

   • Write correct fields, return as normal?
   • Write nothing and return zero?
   • Write nothing and throw?
     • If so, which exception?
   • Wildcard option: Create that column?
   • Behavior depends on underlying database?

7. InsertAsync, single or multiple insert, field not found
   (Entity is missing a field representing a column that exists in the table)

   • Write other fields, leaving empty field as null/zero/empty string, return as normal?
   • Write nothing and return zero?
   • Write nothing and throw?
     • If so, which exception?
   • Behavior depends on underlying database?

8. UpdateAsync
   (Just about all the same questions except reverse the "entity alread exists" logic)

   • No such ID in table
   • Missing fields
   • Extra fields
   • No such table

9. other problems
   (connection bad, connection loss or timeout, transaction in bad state)

   • Surely that's a throw, right?
   • I mean, it has to be?
   • But which exception?

[1] My company works with physical goods rather than at internet scale so we aren't reaching there any time soon (I believe our deepest table only has 3'000'000 entities) but somebody is going to run into that limit, especially if they run at internet-scale and e.g. store log messages in their database.