dbay - npm Package Compare versions

Comparing version 0.104.0 to 0.105.0

lib/query-mixin.js

@@ -54,6 +54,7 @@ (function() {
             return this._query_run_or_execute(first, ...P);
+          case 'object':
           case 'function':
             return this.with_transaction(first, ...P);
         }
-        throw new E.Dbay_wrong_type('^dbay/query@1^', 'a text or a function', type);
+        throw new E.Dbay_wrong_type('^dbay/query@1^', 'a text, an object, or a function', type);
       }
@@ -60,0 +61,0 @@

package.json

 {
   "name": "dbay",
-  "version": "0.104.0",
+  "version": "0.105.0",
   "description": "In-Process, In-Memory & File-Based Relational Data Processing with SQLite, BetterSQLite3",
@@ -5,0 +5,0 @@ "main": "lib/main.js",

README-query.md

@@ -9,3 +9,2 @@
 - [Executing SQL](#executing-sql)
-- [Queries](#queries)
 
@@ -16,4 +15,58 @@ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-### Queries
+One thing that sets DBay apart from other database adapters is the fact that the object returned from `new
+Dbay()` is both the representative of the database opened *and* a callable function. This makes executing
+statements and running queries very concise. This is an excerpt from the [DBay test suite]():
 
-* `db.query()` does job of both `statement.iterate()` and `statement.run()`
+```coffee
+{ Dbay }            = require H.dbay_path
+db                  = new Dbay()
+db ->
+  db SQL"drop table if exists texts;"
+  db SQL"create table texts ( nr integer not null primary key, text text );"
+  db SQL"insert into texts values ( 3, 'third' );"
+  db SQL"insert into texts values ( 1, 'first' );"
+  db SQL"insert into texts values ( ?, ? );", [ 2, 'second', ]
+  #.......................................................................................................
+  T?.throws /cannot start a transaction within a transaction/, ->
+    db ->
+#.........................................................................................................
+T?.throws /UNIQUE constraint failed: texts\.nr/, ->
+  db ->
+    db SQL"insert into texts values ( 3, 'third' );"
+#.........................................................................................................
+rows = db SQL"select * from texts order by nr;"
+rows = [ rows..., ]
+T?.eq rows, [ { nr: 1, text: 'first' }, { nr: 2, text: 'second' }, { nr: 3, text: 'third' } ]
+```
+
+> **Note** In the above `SQL` has been set to `String.raw` and has no further effect on the string it
+> precedes; it is just used as a syntax marker (cool because then you can have nested syntax hiliting).
+
+As shown by [benchmarks](./README-benchmarks.md), a crucial factor for getting maximum performance out of
+using SQLite is strategically placed transactions. SQLite will not ever execute a DB query *outside* of a
+transaction; when no transaction has been explicitly opened with `begin transaction`, the DB engine will
+precede each query implicitly with (the equivalent of) `begin transaction` and follow it with either
+`commit` or `rollback`. This means when a thousand `insert` statements are run, a thousand transactions will
+be started and committed, leavin performance pretty much in the dust.
+
+To avoid that performance hit, users are advised to always start and commit transactions when doing many
+consecutive queries. DBay's callable `db` object makes that easy: just write `db -> many; inserts; here;`
+(JS: `db( () -> { many; inserts; here; })`), i.e. pass a function as the sole argument to `db`, and DBay
+will wrap that function with a transaction. In case an error should occur, DBay guarantees to call
+`rollback` (in a `try ... finally ...` clause). Those who like to make things more explicit can also use
+`db.with_transaction ->`. Both formats allow to pass in a configuration object with an attribute `mode` that
+may be set to [one of `'deferred'`, `'immediate'`, or
+`'exclusive'`](https://www.sqlite.org/lang_transaction.html), the default being `'deferred'`.
+
+Another slight performance hit may be caused by the logic DBay uses to (look up an SQL text in a cache or)
+prepare a statement and then decide whether to call `better-sqlite3`'s' `Database::execute()`,
+`Statement::run()` or `Statement::iterate()`; in order to circumvent that extra work, users may choose to
+fall back on to `better-sqlite3` explicitly:
+
+```coffee
+insert = db.prepare SQL"insert into texts values ( ?, ? );" # returns a `better-sqlite3` `Statement` instance
+db ->
+  insert [ 2, 'second', ]
+```
+
+

README.md

@@ -89,2 +89,3 @@ # DBay
   `Dbay::with_transaction -> ...`.
+* **[+]** allow to call `Dbay::do { mode: 'deferred', }, -> ...`.
 * **[–]** allow to call `Dbay::do -> ...` with an asynchronous function
@@ -91,0 +92,0 @@ * **[+]** make `db = new Dbay()` an instance of `Function` that, when called, runs `Dbay::do()`

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

11908291

increased by0.03%

Lines of code

1164

increased by0.09%

Number of lines in readme file

97

increased by1.04%

No dependency changes