doc (#45)

README.md

@@ -40,8 +40,8 @@ It DOESN'T
     - [Delete](#delete)
     - [Other](#other)
   - [Transaction](#transaction)
-  - [Map rows into structs](#map-rows-into-structs)
-    - [Map rows](#map-rows)
+  - [Find records](#find-records)
+    - [For simple query](#for-simple-query)
     - [For joined table](#for-joined-table)
     - [For outer-joined table](#for-outer-joined-table)
   - [Use query builder](#use-query-builder)
@@ -304,7 +304,7 @@ func OtherQuery(db exql.DB) {
 
 ### Transaction
 
-Transaction with BEGIN~COMMIT/ROLLBACK is done by a `TransactionWithContext`. You don't need to call `BeginTx` and `Commit`/`Rollback` manually.
+Transaction with `BEGIN`~`COMMIT`/`ROLLBACK` is done by `TransactionWithContext`. You don't need to call `BeginTx` and `Commit`/`Rollback` manually and all atomic operations are done within a callback.
 
 ```go
 package main
@@ -337,11 +337,11 @@ func Transaction(db exql.DB) {
 
 ```
 
-### Map rows into structs
+### Find records
 
-To map query results to models, use `Map` method. It maps column records to destination model fields correctly.
+To find records from the database, use `Find`/`FindMany` method. It executes the query and maps results into structs correctly.
 
-#### Map rows
+#### For simple query
 
 ```go
 package main
@@ -484,6 +484,8 @@ func MapSerialOuterJoin(db exql.DB) {
 
 ### Use query builder
 
+`exql/query` package is a low-level API for building complicated SQL statements. See [V2 Release Notes](https://github.com/loilo-inc/exql/blob/main/changelogs/v2.0.md#exqlquery-package) for more details.
+
 ```go
 package main
 
@@ -525,5 +527,5 @@ func CondBulider(db exql.DB) {
 
 ## License
 
-MIT License / Copyright (c) 2020-Present LoiLo inc.
+MIT License / Copyright (c) LoiLo inc.
 

changelogs/v2.0.md

@@ -13,6 +13,7 @@ Software Engineer at LoiLo Inc.
   - [Delete/DeleteContext](#deletedeletecontext)
   - [Query Executors](#query-executors)
   - [Query maker for bulk insertion](#query-maker-for-bulk-insertion)
+- [Finder interface](#finder-interface)
 - [Interface Updates](#interface-updates)
   - [New interfaces](#new-interfaces)
   - [Removed interfaces](#removed-interfaces)
@@ -64,6 +65,35 @@ result, err := db.Exec(q)
 // INSERT INTO users (age,name) VALUES (?,?),(?,?)
 // [20, go, 30, lang]"
 ```
+## Finder interface
+
+A new interface, `Finder` was intoroduced. This is integrated interface of quering records and maping rows into models. In former verison, a typical SELECT query and code were like this:
+
+```go
+rows, err := db.DB().Query(`SELECT * FROM users WHERE id = ?`, 1)
+if err != nil {
+  log.Fatal(err)
+} else {
+  var user model.Users
+  if err := db.Map(rows, &user); err != nil {
+    log.Fatal(err)
+  }
+  log.Printf("%d", user.Id) // -> 1
+}
+```
+
+That can be rewritten in new version briefly:
+
+```go
+var user model.Users
+err := db.Find(query.Q(`SELECT * FROM users WHERE id = ?`, 1), &user)
+if err != nil {
+  log.Fatal(err)
+}
+log.Printf("%d", user.Id) // -> 1
+```
+
+`Mapper` has been deprecated and is going te be removed in the next major version. Faster refactoring is recommended.
 
 ## Interface Updates
 

template/README.md

@@ -40,8 +40,8 @@ It DOESN'T
     - [Delete](#delete)
     - [Other](#other)
   - [Transaction](#transaction)
-  - [Map rows into structs](#map-rows-into-structs)
-    - [Map rows](#map-rows)
+  - [Find records](#find-records)
+    - [For simple query](#for-simple-query)
     - [For joined table](#for-joined-table)
     - [For outer-joined table](#for-outer-joined-table)
   - [Use query builder](#use-query-builder)
@@ -123,17 +123,17 @@ Other queries should be executed by `sql.DB` that got from `DB`.
 
 ### Transaction
 
-Transaction with BEGIN~COMMIT/ROLLBACK is done by a `TransactionWithContext`. You don't need to call `BeginTx` and `Commit`/`Rollback` manually.
+Transaction with `BEGIN`~`COMMIT`/`ROLLBACK` is done by `TransactionWithContext`. You don't need to call `BeginTx` and `Commit`/`Rollback` manually and all atomic operations are done within a callback.
 
 ```go
 {{.Tx}}
 ```
 
-### Map rows into structs
+### Find records
 
-To map query results to models, use `Map` method. It maps column records to destination model fields correctly.
+To find records from the database, use `Find`/`FindMany` method. It executes the query and maps results into structs correctly.
 
-#### Map rows
+#### For simple query
 
 ```go
 {{.MapRows}}
@@ -153,11 +153,13 @@ To map query results to models, use `Map` method. It maps column records to dest
 
 ### Use query builder
 
+`exql/query` package is a low-level API for building complicated SQL statements. See [V2 Release Notes](https://github.com/loilo-inc/exql/blob/main/changelogs/v2.0.md#exqlquery-package) for more details.
+
 ```go
 {{.QueryBuilder}}
 ```
 
 ## License
 
-MIT License / Copyright (c) 2020-Present LoiLo inc.
+MIT License / Copyright (c) LoiLo inc.