Inserting

Draft.

Actually: I'm going to write this as an integration test. This way we can confirm all examples work.

---

PetaPoco supports very flexible methods for inserting data. The easiest way to demonstration how to insert data is probably through a couple of working examples. However, first we should cover the API as these working examples will be of course making use of it.

The API:

        /// <summary>
        ///     Performs an SQL Insert.
        /// </summary>
        /// <param name="poco">The POCO object that specifies the column values to be inserted.</param>
        /// <returns>The auto allocated primary key of the new record, or null for non-auto-increment tables.</returns>
        /// <remarks>
        ///     The name of the table, it's primary key and whether it's an auto-allocated primary key are retrieved
        ///     from the POCO's attributes
        /// </remarks>
        object Insert(object poco);

        /// <summary>
        ///     Performs an SQL Insert.
        /// </summary>
        /// <param name="tableName">The name of the table to insert into.</param>
        /// <param name="poco">The POCO object that specifies the column values to be inserted.</param>
        /// <returns>The auto allocated primary key of the new record, or null for non-auto-increment tables.</returns>
        object Insert(string tableName, object poco);

        /// <summary>
        ///     Performs an SQL Insert.
        /// </summary>
        /// <param name="tableName">The name of the table to insert into.</param>
        /// <param name="primaryKeyName">The name of the primary key column of the table.</param>
        /// <param name="poco">The POCO object that specifies the column values to be inserted.</param>
        /// <returns>The auto allocated primary key of the new record, or null for non-auto-increment tables.</returns>
        object Insert(string tableName, string primaryKeyName, object poco);

        /// <summary>
        ///     Performs an SQL Insert.
        /// </summary>
        /// <param name="tableName">The name of the table to insert into.</param>
        /// <param name="primaryKeyName">The name of the primary key column of the table.</param>
        /// <param name="autoIncrement">True if the primary key is automatically allocated by the DB.</param>
        /// <param name="poco">The POCO object that specifies the column values to be inserted.</param>
        /// <returns>The auto allocated primary key of the new record, or null for non-auto-increment tables.</returns>
        /// <remarks>
        ///     Inserts a poco into a table. If the poco has a property with the same name
        ///     as the primary key, the id of the new record is assigned to it. Either way,
        ///     the new id is returned.
        /// </remarks>
        object Insert(string tableName, string primaryKeyName, bool autoIncrement, object poco);

Examples object Insert(object poco);

Example 1) Basic POOC fully mapped.

// Insert the person (auto increment)
var personId = db.Insert(person);

// personId equals person.Id as PetaPoco set the value for us.

// Get the inserted person by ID.
var p = db.Single<Person>(person.Id);

Example 2) Related POOCs

var personId = db.Insert(person);
order.PersonId = personId;
var orderId = db.Insert(order);

// OR if you don't have a use for the returned IDs

order.PersonId = db.Insert(person);
db.Insert(order);

Examples object Insert(string tableName, object poco);

Example 3) Archived people

var person = db.Single<Person>(999);
db.Delete(person);
db.Insert("DeletedPeople", person);

Example 4) A POCO without being mapped

-- schema
CREATE TABLE Logs (
    AddedOn DATETIME,
    Content VARCHAR
)

``` c#
var log = new Log { AddedOn = DateTime.UTCNow, Content = "Dancing hats" };
db.Insert("Logs", log);