Update README.md

Author: mythz

README.md

@@ -866,6 +866,51 @@ var track = db.SingleById<Track>(1);
 var tracks = db.SelectByIds<Track>(new[]{ 1,2,3 });
 ```
 
+### Ensure APIs
+
+The new `Ensure()` API on OrmLite's typed `SqlExpression<T>` can be used to ensure that a condition is always applied irrespective
+of other conditions, e.g:
+
+#### Typed API
+
+```csharp
+var q = db.From<Rockstar>();
+q.Ensure(x => x.Id == 1); //always applied
+
+//...
+q.Where(x => x.Age == 27);
+q.Or(x => x.LivingStatus == LivingStatus.Dead);
+
+var rows = db.Select(q);
+```
+
+#### Custom Parameterized SQL Expression
+
+Custom SQL Ensure parameterized expressions:
+
+```csharp
+ q.Ensure("Id = {0}", 1); 
+```
+
+#### Multiple Ensure expressions
+
+```csharp
+var q = db
+    .From<Rockstar>()
+    .Join<RockstarAlbum>((r,a) => r.Id == a.RockstarId);
+
+q.Ensure<Rockstar,RockstarAlbum>((r,a) => a.Name == "Nevermind" && r.Id == a.RockstarId);
+
+q.Where(x => x.Age == 27)
+ .Or(x => x.LivingStatus == LivingStatus.Dead);
+
+q.Ensure(x => x.Id == 3);
+
+var rows = db.Select(q);
+```
+
+These APIs are useful for mandatory filters like "Soft Deletes" and Multitenant records.
+
 ## Nested Typed Sub SqlExpressions
 
 The `Sql.In()` API supports nesting and combining of multiple Typed SQL Expressions together 
@@ -898,23 +943,39 @@ var names = new List<string>{ "foo", "bar", "qux" };
 var results = db.SqlList<Table>("SELECT * FROM Table WHERE Name IN (@names)", new { names });
 ```
 
+### Spread Util
+
+The `SqlSpread()` API is useful to generate an escaped list of parameterized values for use in SQL `IN()` statements and SQL functions:
+
+```csharp
+var dialect = db.Dialect();
+dialect.SqlSpread(1, 2, 3);         //= 1,2,3
+dialect.SqlSpread("A", "B", "C");   //= 'A','B','C'
+dialect.SqlSpread("A'B", "C\"D");   //= 'A''B','C\"D'
+```
+
 ### Custom SQL using PostgreSQL Arrays
 
-If using PostgreSQL you can take advantage of its complex Array Types and utilize its [Array Functions and Operators](https://www.postgresql.org/docs/9.6/functions-array.html), e.g:
+The `PgSql.Array()` provides a typed API for generating [PostgreSQL Array Expressions](https://www.postgresql.org/docs/current/arrays.html), e.g:
 
 ```csharp
-var ids = new[]{ 1, 2, 3};
-var q = Db.From<Table>()
-    .Where("ARRAY[{0}] && ref_ids", ids.Join(","))
-var results = db.Select(q);
+PgSql.Array(1,2,3)     //= ARRAY[1,2,3]
+var strings = new[]{ "A","B","C" };
+PgSql.Array(strings)   //= ARRAY['A','B','C']
 ```
 
-When comparing a string collection you can use `SqlInValues` to create a quoted SQL IN list, e.g:
+Which you can safely use in Custom SQL Expressions that use PostgreSQL's native ARRAY support:
 
 ```csharp
-var q = Db.From<Table>()
-    .Where($"ARRAY[{new SqlInValues(cities).ToSqlInString()}] && cities");
-var results = db.Select(q);
+q.And($"{PgSql.Array(anyTechnologyIds)} && technology_ids")
+q.And($"{PgSql.Array(labelSlugs)} && labels");
+```
+
+If you want and empty collection to return `null` instead of an empty `ARRAY[]` you can use the `nullIfEmpty` overload:
+
+```csharp
+PgSql.Array(new string[0], nullIfEmpty:true)      //= null
+PgSql.Array(new[]{"A","B","C"}, nullIfEmpty:true) //= ARRAY['A','B','C']
 ```
 
 ### Lazy Queries
@@ -972,7 +1033,7 @@ var q = db.From<Customer>()
 var dbCustomers = db.Select<Customer>(q);
 ```
 
-This query rougly maps to the following SQL:
+This query roughly maps to the following SQL:
 
 ```sql
 SELECT Customer.* 
@@ -1338,6 +1399,59 @@ Custom Key/Value Dictionary:
 Dictionary<string,string> rows = db.Dictionary<string,string>(q);
 ```
 
+### Dictionary APIs
+
+OrmLite's Dictionary APIs allow you to customize which parts of a Data Model should be modified by 
+converting it into then manipulating an Object Dictionary, e.g:
+
+#### Insert by Dictionary
+
+```csharp
+var row = new Person { FirstName = "John", LastName = "Smith" };
+Dictionary<string,object> obj = row.ToObjectDictionary();
+obj[nameof(Person.LastName)] = null;
+
+row.Id = (int) db.Insert<Person>(obj, selectIdentity:true);
+```
+
+#### Update by Dictionary
+
+```csharp
+Person row = db.SingleById<Person>(row.Id);
+var obj = row.ToObjectDictionary();
+obj[nameof(Person.LastName)] = "Smith";
+db.Update<Person>(obj);
+```
+
+#### UpdateOnly by Dictionary
+
+```csharp
+// By Primary Key Id
+var fields = new Dictionary<string, object> {
+    [nameof(Person.Id)] = 1,
+    [nameof(Person.FirstName)] = "John",
+    [nameof(Person.LastName)] = null,
+};
+
+db.UpdateOnly<Person>(fields);
+
+// By Custom Where Expression
+var fields = new Dictionary<string, object> {
+    [nameof(Person.FirstName)] = "John",
+    [nameof(Person.LastName)] = null,
+};
+
+db.UpdateOnly<Person>(fields, p => p.LastName == "Hendrix");
+```
+
+#### Delete by Dictionary
+
+```csharp
+db.Delete<Rockstar>(new Dictionary<string, object> {
+    ["Age"] = 27
+});
+```
+
 ### BelongsTo Attribute
 
 The `[BelongTo]` attribute can be used for specifying how Custom POCO results are mapped when the resultset is ambiguous, e.g:
@@ -2247,6 +2361,41 @@ CREATE TABLE "PocoTable"
 
 > OrmLite replaces any variable placeholders with the value in each RDBMS DialectProvider's `Variables` Dictionary.
 
+### Custom Insert and Update Expressions
+
+The `[CustomInsert]` and `[CustomUpdate]` attributes can be used to override what values rows are inserted during INSERT's and UPDATE's. 
+
+We can use this to insert a salted and hashed password using PostgreSQL native functions:
+
+```csharp
+public class CustomSqlUser
+{
+    [AutoIncrement]
+    public int Id { get; set; }
+
+    public string Email { get; set; }
+
+    [CustomInsert("crypt({0}, gen_salt('bf'))"),
+     CustomUpdate("crypt({0}, gen_salt('bf'))")]
+    public string Password { get; set; }
+}
+
+var user = new CustomSqlUser {
+    Email = "[email protected]", 
+    Password = "secret"
+};
+db.Insert(user);
+```
+
+We can then use `Sql.Custom()` to create a partially typed custom query to match on the hashed password, e.g:
+
+```csharp
+var quotedSecret = db.Dialect().GetQuotedValue("secret");
+var q = db.From<CustomSqlUser>()
+    .Where(x => x.Password == Sql.Custom($"crypt({quotedSecret}, password)"));
+var row = db.Single(q);
+```
+
 #### Pre / Post Custom SQL Hooks when Creating and Dropping tables 
 
 Pre / Post Custom SQL Hooks allow you to inject custom SQL before and after tables are created or dropped, e.g:
@@ -3155,6 +3304,22 @@ PostgreSqlDialect.Provider.RegisterConverter<List<DateTime>>(new PostgreSqlDateT
 PostgreSqlDialect.Provider.RegisterConverter<List<DateTimeOffset>>(new PostgreSqlDateTimeOffsetTimeStampTzArrayConverter());
 ```
 
+### PostgreSQL Params
+
+The `PgSql.Param()` API provides a resolve the correct populated `NpgsqlParameter` and `NpgsqlDbType` from a C# Type
+which can be used to query custom PostgreSQL Data Types in APIs that accept `IDbDataParameter` parameters, e.g:
+
+```csharp
+public class FunctionResult
+{
+    public int[] Val { get; set; }
+}
+
+var p = PgSql.Param("paramValue", testVal);
+var sql = "SELECT * FROM my_func(@paramValue)";
+var rows = db.Select<FunctionResult>(sql, new [] { p });
+```
+
 ### Hstore support
 
 To use `hstore`, its extension needs to be enabled in your PostgreSQL RDBMS by running: