[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/emacsql 86687b6ba3 067/427: Flesh out more README.
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/emacsql 86687b6ba3 067/427: Flesh out more README. |
Date: |
Tue, 13 Dec 2022 02:59:28 -0500 (EST) |
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
- [nongnu] elpa/emacsql 54247e4b5e 127/427: Add another insertion unit test., (continued)
- [nongnu] elpa/emacsql 54247e4b5e 127/427: Add another insertion unit test., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql aa9283ca0a 132/427: Allow sub-selects with :from., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql c236aa8437 144/427: Remove extra space., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 75ea77c9a0 149/427: Add an "as" operator, greatly simplifying :from., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 213bb71b7a 152/427: Add :having expander., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 8123020ca7 153/427: Make and and or operators variadic., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 76bf0c34dc 038/427: Add rudimentary :where expander., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql afe64ca63a 040/427: Fix emacsql-add-expander example., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 72145a1627 045/427: Allow for multi-arity keyword expanders., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql f54142f1eb 062/427: Argument list checking in emacsql-format., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 86687b6ba3 067/427: Flesh out more README.,
ELPA Syncer <=
- [nongnu] elpa/emacsql a306de980a 070/427: Add :delete keyword., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql afa9aa5194 072/427: Add :into expander., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 8f59fe6e80 073/427: Add a vector escape., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql eb3283990e 077/427: Drop emacsql-create., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 66df2afbf1 091/427: Simplify start-process call., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql e956d91f99 095/427: Add -identifier to emacsql-escape., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 8aade12994 101/427: Add a unit test for vector update., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql beb0e00b9e 100/427: Rename emacsql--vars-collect., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql ee2877dab0 106/427: Clearer error message from escape identifier., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql e9b77b4774 112/427: Add a test for CREATE TABLE., ELPA Syncer, 2022/12/13