[nongnu] elpa/emacsql 86687b6ba3 067/427: Flesh out more README.

[ELPA Syncer]

branch: elpa/emacsql
commit 86687b6ba3e0830da7179b4ce218da7b571debbf
Author: Christopher Wellons <wellons@nullprogram.com>
Commit: Christopher Wellons <wellons@nullprogram.com>

    Flesh out more README.
---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 42 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 7d3aeea714..9508383903 100644
--- a/README.md
+++ b/README.md
@@ -15,32 +15,48 @@ objects.
 
 Requires Emacs 24 or later.
 
-## Usage
+## Example Usage
 
 ```el
-(defvar db (emacsql-connect "company.db"))
+(defvar db (emacsql-connect "/var/lib/company.db"))
 
 ;; Create a table. A table identifier can be any kind of lisp value.
-(emacsql-create db 'employees [name id salary])
+(emacsql db [:create-table people [name id salary]])
 
 ;; Or optionally provide column constraints.
-(emacsql-create db 'employees [name (id integer :unique) (salary float)])
+(emacsql db [:create-table people [name (id integer :unique) (salary float)]])
 
 ;; Insert some data:
-(emacsql-insert db 'employees ["Jeff"  1000 60000.0]
-                              ["Susan" 1001 64000.0])
+(emacsql-insert db 'people ["Jeff"  1000 60000.0]
+                           ["Susan" 1001 64000.0])
 
 ;; Query the database for results:
-(emacsql db [:select [name id] :from employees :where (> salary 62000)])
+(emacsql db [:select [name id] :from people :where (> salary 62000)])
 ;; => (("Susan" 1001))
 
 ;; Queries can be templates, using $1, $2, etc.:
-(emacsql db
-         [:select [name id] :from employees :where (> salary $1)]
-         50000)
+(emacsql db [:select [name id] :from people :where (> salary $1)] 50000)
 ;; => (("Jeff" 1000) ("Susan" 1001))
 ```
 
+## Schema
+
+A table schema is a vector of column specification. A column
+identifier is a symbol and a specification can either be just this
+symbol or it can include constraints, such as type and uniqueness.
+Because Emacsql stores entire lisp objects as values, the only
+relevant types are `integer`, `float`, and `object` (default).
+
+Additional contraints include `:primary` (aka `PRIMARY KEY`),
+`:unique` (aka `UNIQUE`), `:non-nil` (aka `NOT NULL`).
+
+```el
+;; Example schema:
+[name (badge-no integer :primary :unique) address]
+```
+
+The lisp object `nil` corresponds 1:1 with `NULL` in the database.
+
 ## Operators
 
 Emacsql currently supports the following expression operators, named
@@ -83,30 +99,38 @@ When multiple keywords appear in sequence, Emacsql will 
generally
 concatenate them with a dash, e.g. `CREATE TABLE` becomes
 `:create-table`.
 
- * `:create-table <ident> <schema>`
+#### :create-table `<ident>` `<schema>`
 
 Provides `CREATE TABLE`.
 
-    ex. [:create-table employees [name (id integer :primary) (salary float)]]
+```el
+[:create-table employees [name (id integer :primary) (salary float)]]
+```
 
- * `:drop-table <ident>`
+#### :drop-table `<ident>`
 
 Provides `DROP TABLE`.
 
-    ex. [:drop-table employees]
+```el
+[:drop-table employees]
+```
 
- * `:select <column-spec>`
+#### :select `<column-spec>`
 
 Provides `SELECT`. `column-spec` can be a `*` symbol or a vector of
 column identifiers, optionally as expressions.
 
-    ex. [:select [name (/ salary 52)] ...]
+```el
+[:select [name (/ salary 52)] ...]
+```
 
- * `:from <ident>`
+#### :from `<ident>`
 
 Provides `FROM`.
 
-    ex. [... :from employees]
+```el
+[... :from employees]
+```
 
 ### Templates