Refactor the gateway

- Add Query builder
- Refactor Routine and Query statements
- Use embed package instead of parcello

Author: iamralch

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,11 @@
 ### Description
+
 Please explain the changes you made here.
 
 ### Checklist
+
 - [ ] Code compiles correctly
-- [ ] Created tests which fail without the change (if possible)
+- [ ] Created tests that fail without the change (if possible)
 - [ ] All tests passing
 - [ ] Extended the README.md / documentation, if necessary
-- [ ] Added myself / the copyright holder to the CONTRIBUTORS file
+- [ ] Added me / the copyright holder to the CONTRIBUTORS file

README.md

@@ -6,34 +6,25 @@
 [![Coverage][codecov-img]][codecov-url]
 [![Go Report Card][report-img]][report-url]
 
-*Golang Query Executor and Database Connector*
+The package facilitates execution of SQL scripts generated by
+[prana][prana-url]. Also it provides a query builder and object relation mapper.
+Note that it is in BETA. We may introduce breaking changes until we reach
+version 1.0.
 
 [![ORM][orm-img]][orm-url]
 
-## Overview
-
-ORM is a package that facilitates execution of [loukoum][loukoum-url] queries
-as well as migrations and scripts generate by [prana][prana-url].
-
 ## Installation
 
 ```console
 $ go get -u github.com/phogolabs/orm
 ```
 
-## Introduction
-
-Note that ORM is in BETA. We may introduce breaking changes until we reach
-v1.0.
-
-Gateway API facilitates object relation mapping and query building by using
-[loukoum](loukoum-url) and [sqlx][sqlx-url].
+## Getting Started
 
 Let's first import all required packages:
 
 ```golang
 import (
-  lk "github.com/ulule/loukoum"
   "github.com/phogolabs/orm"
 )
 ```
@@ -47,149 +38,30 @@ if err != nil {
 }
 ```
 
-### SQL Queries
-
-All [loukoum][loukoum-url] queries are complaint with `orm.Query` interface:
-
-```golang
-// Query returns the underlying query
-type Query interface {
-	// Query prepares the query
-	Query() (string, []Param)
-}
-
-// NamedQuery returns the underlying query
-type NamedQuery interface {
-	// Query prepares the query
-	NamedQuery() (string, map[string]Param)
-}
-```
-
-That allows easy execution of all kind of queries.
-
-Because the package is empowered by [sqlx][sqlx-url]. It can perform field
-mapping of Golang structs by reading a `db` field tag. Let's assume that we
-have the following struct:
-
-```golang
-// Package model contains an object model of database schema 'default'
-// Auto-generated at Thu Apr 19 21:36:35 CEST 2018
-package model
-
-import null "gopkg.in/volatiletech/null.v6"
-
-// User represents a data base table 'users'
-type User struct {
-	// ID represents a database column 'id' of type 'INT PRIMARY KEY NOT NULL'
-	ID int `db:"id,primary_key,not_null" json:"id" xml:"id" validate:"required"`
-
-	// FirstName represents a database column 'first_name' of type 'TEXT NOT NULL'
-	FirstName string `db:"first_name,not_null" json:"first_name" xml:"first_name" validate:"required"`
-
-	// LastName represents a database column 'last_name' of type 'TEXT NULL'
-	LastName null.String `db:"last_name,null" json:"last_name" xml:"last_name" validate:"-"`
-}
-```
-
-#### Insert a new record
-
-```golang
-
-query := lk.Insert("users").
-	Set(
-		lk.Pair("first_name", "John"),
-		lk.Pair("last_name", "Doe"),
-	)
-
-if _, err := gateway.Exec(query); err != nil {
-  return err
-}
-```
-
-#### Select all records
-
-```golang
-query := lk.Select("id", "first_name", "last_name").From("users")
-users := []User{}
-
-if err := gateway.Select(&users, query); err != nil {
-  return err
-}
-```
-
-#### Select a record
-
-```golang
-query := lk.Select("id", "first_name", "last_name").
-	From("users").
-	Where(lk.Condition("first_name").Equal("John"))
-
-user := User{}
-
-if err := gateway.SelectOne(&user, query); err != nil {
-  return err
-}
-```
-
-You can read more details about [loukoum][loukoum-url] on their repository.
-
-#### RQL Support
-
-The package support [RQL](https://github.com/a8m/rql) queries. RQL provides a
-simple and light-weight API for adding dynamic querying capabilities to
-web-applications that use SQL-based database.
-
-Let's have the following query that is received via HTTP:
-
-```json
-{
-  "$or": [
-    { "city": "TLV" },
-    { "zip": { "$gte": 49800, "$lte": 57080 } }
-  ]
-}
-```
-
-Then we can process it in the following way:
+## SQL Migrations
 
-```golang
-param := &orm.RQLQuery{}
-
-err := json.Unmarshal(body, param)
-if err != nil {
-  panic(err)
-}
-
-rows, err := gateway.Query(orm.RQL("addresses", param))
-```
-
-### SQL Migrations with Prana
-
-You can execute the migration generated by [Prana][prana-url]. First, you
-should load the migration directory by using [Parcello][parcello-url]. You can
-load it from embedded resource or from the local directory:
+You can execute the migration generated by [prana][prana-url]. For that you have
+to use either [embed][embed-url] package or [os][os-url] package.
 
 ```golang
-if err := gateway.Migrate(parcello.Dir("./database/migration")); err != nil {
+if err := gateway.Migrate(resource); err != nil {
 	return err
 }
 ```
 
-### SQL Scripts and Routines with Prana
+## SQL Queries
 
-ORM provides a way to work with embeddable SQL scripts. It can understand
-[SQL Scripts](https://github.com/phogolabs/prana#sql-scripts-and-commands) from
-file and execute them as standard SQL queries. Let's assume that we have SQL
-query named `show-sqlite-master`.
+The package provides a way to work with embeddable SQL scripts. It understands predefined files with [SQL Scripts](https://github.com/phogolabs/prana#sql-scripts-and-commands).
 
-Let's first load the SQL script from file:
+It executes them as standard SQL queries. Let's define a SQL routines named `insert-user` and `select-all-users`:
 
 ```
--- name: show-sqlite-master
-SELECT * FROM sqlite_master;
+-- name: insert-user
+INSERT INTO users (id, first_name, last_name)
+VALUES (:id, :first_name, :last_name);
 
--- named: show-table
-SELECT * FROM {{table}};
+-- named: select-all-users
+SELECT * FROM users;
 ```
 
 ```golang
@@ -201,29 +73,26 @@ if err = gateway.ReadFrom(file); err != nil {
 Then you can execute the desired script by just passing its name:
 
 ```golang
-_, err = gateway.Exec(orm.Routine("show-sqlite-master"))
+routine := orm.Routine("select-all-users")
+// execute the routine
+_, err = gateway.All(context.TODO(), routine, &users)
 ```
 
-Also you can Raw SQL Scripts from your code, you should follow this
-example:
-
 ```golang
-rows, err := gateway.Query(orm.SQL("SELECT * FROM users WHERE id = ?", 5432))
+routine := orm.Routine("insert-user", &user)
+// execute the routine
+_, err = gateway.Exec(context.TODO(), routine)
 ```
 
-Also you can use [handlerbars](https://handlebarsjs.com) to template your
-query. But be aware how you use it in order not to open possible SQL
-injections:
+Also you can execute raw SQL Scripts from your code:
 
 ```golang
-param := orm.Map{
-  "table": "users",
-}
-
-_, err = gateway.Exec(orm.Routine("show-table", param))
+query := orm.Query("SELECT * FROM users WHERE id = ?", 5432)
+// fetch the records as a slice of users
+rows, err := gateway.Only(context.TODO(), query, &user)
 ```
 
-### Example
+## Example
 
 You can check our [Getting Started Example](/example).
 
@@ -242,7 +111,7 @@ We are open for any contributions. Just fork the
 [logo-author-url]: https://www.freepik.com/free-photos-vectors/tree
 [logo-license]: http://creativecommons.org/licenses/by/3.0/
 [orm-url]: https://github.com/phogolabs/orm
-[orm-img]: doc/img/logo.png
+[orm-img]: media/img/logo.png
 [codecov-url]: https://codecov.io/gh/phogolabs/orm
 [codecov-img]: https://codecov.io/gh/phogolabs/orm/branch/master/graph/badge.svg
 [action-img]: https://github.com/phogolabs/orm/workflows/main/badge.svg
@@ -252,7 +121,7 @@ We are open for any contributions. Just fork the
 [godoc-img]: https://godoc.org/github.com/phogolabs/orm?status.svg
 [license-img]: https://img.shields.io/badge/license-MIT-blue.svg
 [software-license-url]: LICENSE
-[loukoum-url]: https://github.com/ulule/loukoum
-[parcello-url]: https://github.com/phogolabs/parcello
+[embed-url]: https://golang.org/pkg/embed
+[os-url]: https://golang.org/pkg/os
 [prana-url]: https://github.com/phogolabs/prana
 [sqlx-url]: https://github.com/jmoiron/sqlx