[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/emacsql 64c3a03d62 169/427: Flesh out some more README.
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/emacsql 64c3a03d62 169/427: Flesh out some more README. |
Date: |
Tue, 13 Dec 2022 02:59:39 -0500 (EST) |
branch: elpa/emacsql
commit 64c3a03d6258dffbe85edcf5a36e739daf07c6a4
Author: Christopher Wellons <wellons@nullprogram.com>
Commit: Christopher Wellons <wellons@nullprogram.com>
Flesh out some more README.
---
README.md | 37 +++++++++++++++++++++++++------------
1 file changed, 25 insertions(+), 12 deletions(-)
diff --git a/README.md b/README.md
index 98027174c5..28543f0367 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,14 @@
# Emacsql
-Emacsql is a high-level Emacs Lisp front-end for SQLite. It is
-currently a work-in-progress as the s-expression query language is
-still being hammered out.
+Emacsql is a high-level Emacs Lisp front-end for SQLite (primarily),
+PostgreSQL, and potentially other SQL databases. It is currently a
+work-in-progress (90% complete) because the s-expression query
+language is still being hammered out.
-It works by keeping a `sqlite3` inferior process running (a
-"connection") for interacting with the back-end database. Connections
-are automatically cleaned up if they are garbage collected. All
-requests are synchronous.
+It works by keeping a `sqlite3` (or `psql`) inferior process running
+(a "connection") for interacting with the back-end database.
+Connections are automatically cleaned up if they are garbage
+collected. All requests are synchronous.
Any [readable lisp value][readable] can be stored as a value in
Emacsql, including numbers, strings, symbols, lists, vectors, and
@@ -15,17 +16,15 @@ closures. Emacsql has no concept of "TEXT" values; it's all
just lisp
objects. The lisp object `nil` corresponds 1:1 with `NULL` in the
database.
-Requires Emacs 24 or later and SQLite 3 or later.
+Requires Emacs 24 or later.
Due to [bad behavior from SQLite on Windows][stderr] Emacsql will
-*not* signal error messages for invalid statements on this platform.
-Fortunately this would only be an issue during package development and
-shouldn't impact normal use of the database.
+*not* signal error messages for problems on this platform.
## Example Usage
```el
-(defvar db (emacsql-connect "/var/lib/company.db"))
+(defvar db (emacsql-connect "~/company.db"))
;; Create a table. Table and column identifiers are symbols.
(emacsql db [:create-table people [name id salary]])
@@ -368,6 +367,20 @@ from the command line and allows for storage of Emacs
richer data
types. This is an efficient, ACID-compliant database specifically for
Emacs.
+## Creating a New Front-end
+
+Emacsql uses EIEIO so that interactions with a connection occur
+through generic functions. You need to define a new class that
+inherits from `emacsql-connection`.
+
+ * Implement `emacsql-waiting-p`, `emacsql-close`, and `emacsql`.
+ * Provide a constructor that initializes the connection and calls
+ `emacsql-register` (for automatic connection cleanup).
+ * Ensure that you properly read NULL as nil (hint: ask your back-end
+ to print it that way).
+
+The provided implementations should serve as useful examples.
+
## See Also
* [SQLite Documentation](https://www.sqlite.org/docs.html)
- [nongnu] elpa/emacsql 4206b17f39 134/427: Add support for AS with CREATE TABLE., (continued)
- [nongnu] elpa/emacsql 4206b17f39 134/427: Add support for AS with CREATE TABLE., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 6c32f02139 137/427: Add emacsql-thread macro., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 54c180017e 138/427: Add :pragma and note in README., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 5e2ab842f7 139/427: Add foreign key test., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 42c2fd7569 145/427: Tweak limitation wording., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql fe0c7004fc 146/427: Add :begin, :commit, and :rollback., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 2550196816 162/427: Drop SQLite version requirements., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 9a1b4209ba 164/427: Add PostgreSQL front-end., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 5f4c2ed5a7 166/427: Add emacsql-psql-unavailable-p., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 1d0ef4011c 167/427: Make emacsql-connection abstract., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 64c3a03d62 169/427: Flesh out some more README.,
ELPA Syncer <=
- [nongnu] elpa/emacsql 9f6c10eca0 172/427: Move error checking out to helper mix-in., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 4f76b94f7c 168/427: Set psql to print nil for NULL., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 7434263d82 174/427: Oops, drop leftover function call., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql ca62adc4b2 177/427: Add debug argument to emacsql-psql., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql afef528d81 179/427: Fix memoization to include type map., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql b2f2dd37cf 178/427: Allow connection to specify their own types., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 4aa889882d 182/427: Fix slot allocation on emacsql-connection., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 769abe20fa 183/427: Don't rely on a closure in cleanup hook., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql e9efb0803e 185/427: Oops, include the reap source., ELPA Syncer, 2022/12/13
- [nongnu] elpa/emacsql 5962268f83 184/427: Split off reaper code., ELPA Syncer, 2022/12/13