cordova-sqlite-legacy-express-core 1.0.0

CHANGES.md

@@ -1,59 +1,55 @@
 # Changes
 
-###### cordova-sqlite-legacy-express-core 1.0.0-pre4
+###### cordova-sqlite-legacy-express-core 1.0.0
 
 - Workaround solution to BUG litehelpers/Cordova-sqlite-storage#666 (hanging transaction in case of location reload/change)
 - selfTest simulate scenario & test solution to BUG litehelpers/Cordova-sqlite-storage#666 (also includes string test and test of effects of location reload/change in this version branch, along with another internal check)
 - Drop engine constraints in package.json & plugin.xml (in this version branch)
 - Remove Lawnchair adapter from this version branch
 - Support macOS platform with builtin libsqlite3.dylib framework in this version branch
 
-## 1.2.2
+### cordova-sqlite-storage 1.2.2
 
 - Self-test function to verify ability to open/populate/read/delete a test database
 - Read BLOB as Base-64 DISABLED in Android version (was already disabled for iOS)
 
-## 1.2.1
+### cordova-sqlite-storage 1.2.1
 
 - Close Android SQLiteStatement after INSERT/UPDATE/DELETE
 - Specify minimum Cordova version 6.0.0
 - Lawnchair adapter fix: Changed remove method to work with key array
 
-## 1.2.0
+### cordova-sqlite-storage 1.2.0
 
 - Rename Lawnchair adapter to prevent clash with standard webkit-sqlite adapter
 - Support location: 'default' setting in openDatabase & deleteDatabase
 
-## 0.8.5
+### cordova-sqlite-storage 0.8.5
 
 - More explicit iosDatabaseLocation option
 - iOS database location is now mandatory
 - Split-up of some more spec test scripts
 
-## 0.8.2
+### cordova-sqlite-storage 0.8.2
 
 - Workaround fix for empty readTransaction issue (litehelpers/Cordova-sqlite-storage#409)
 - Split spec/www/spec/legacy.js into db-open-close-delete-test.js & tx-extended.js
 
-## 0.8.0
+### cordova-sqlite-storage 0.8.0
 
 - Simple sql batch transaction function
 - Echo test function
-- Remove extra runInBackground: step from iOS version
-- Android-sqlite-connector (NDK) support removed from this version branch
-- Windows version removed from this version branch
-- Java source of Android version now using io.sqlc package
-
-## 0.7.15-pre
-
 - All iOS operations are now using background processing (reported to resolve intermittent problems with cordova-ios@4.0.1)
+- Java source of Android version now using io.sqlc package
+- Drop Android-sqlite-connector support
+- Drop WP(8) and Windows support
 
-## 0.7.14
+### 0.7.14
 
 - REGEXP support completely removed from this version branch
 - Remove src/android/libs/.gitignore (inadvertently added in 0.7.13)
 
-## 0.7.13
+### 0.7.13
 
 - REGEXP support partially removed from this version branch
 - Rename Windows C++ Database close function to closedb to resolve conflict for Windows Store certification
@@ -62,79 +58,79 @@
 - Amazon Fire-OS support removed
 - Fix conversion warnings in iOS version
 
-## 0.7.12
+### 0.7.12
 
 - Fix to Windows "Universal" version to support big integers
 - Implement database close and delete operations for Windows "Universal"
 - Fix readTransaction to skip BEGIN/COMMIT/ROLLBACK
 
-## 0.7.11
+### 0.7.11
 
 - Fix plugin ID in plugin.xml to match npm package ID
 - Unpacked sqlite-native-driver.so libraries from jar
 - Fix conversion of INTEGER type (iOS version)
 - Disable code to read BLOB as Base-64 (iOS version) due to https://issues.apache.org/jira/browse/CB-9638
 
-## 0.7.10
+### 0.7.10
 
 - Use Android-sqlite-connector instead of sqlite4java
 
-## 0.7.9
+### 0.7.9
 
 - Build iOS and Windows versions with sqlite 3.8.10.2 embedded
 - Fix plugin id to match npm package id
 
-## 0.7.8
+### 0.7.8
 
 - Support FTS3/FTS4 and R-Tree in iOS and Windows "Universal" (8.1) versions
 - Build ARM target with Function Level Linking ref: http://www.monkey-x.com/Community/posts.php?topic=7739
 - SQLite3.Windows.vcxproj and SQLite3.WindowsPhone.vcxproj in their own directories to avoid problems due to temporary files
 
-## 0.7.7
+### 0.7.7
 
 - include build of sqlite4java for Android x86_64 and arm-64
 - clean publish to plugins.cordova.io
 
-## 0.7.6
+### 0.7.6
 
 - Small fix to plugin id
 - Disable use of gethostuuid() in sqlite3.c (only used in iOS version)
 - published to plugins.cordova.io - [BUG] published extra junk in workarea, causing problems with Windows (Universal) version
 
-## 0.7.5
+### 0.7.5
 
 - Windows (Universal) version now supports both Windows 8.1 and Windows Phone 8.1
 - iOS and Windows versions are now built with sqlite 3.8.9 embedded
 - Improved locking style and other optimizations applied for iOS version
 
-## 0.7.4
+### 0.7.4
 
 - iOS and Windows (8.1) versions built to keep non-essential temporary sqlite files in memory
 - Option to use legacy Android database library, with Android locking/closing issue (BUG #193) workaround included again
 
-## 0.7.3
+### 0.7.3
 
 - insertId & rowsAffected implemented for Windows (8.1)
 - plugin id changed
 
-## 0.7.2
+### 0.7.2
 
 - Android version with sqlite4java (sqlite 3.8.7 embedded), which solves BUG #193: Android closing/locking issue (ICU-UNICODE integration is now missing)
 - iOS version fixed to override the correct pluginInitialize method and built with sqlite 3.8.8.3 embedded
 
-## 0.7.1
+### 0.7.1
 
 - Project renamed
 - Initial version for Windows (8.1) [with sqlite 3.8.8.3 embedded]
 - Abort initially pending transactions for db handle (due to incorrect password key, for example) [from Cordova-sqlcipher-storage]
 - WP7 build enabled (NOT TESTED)
 
-## 1.0.6
+### 1.0.6
 
 - Proper handling of transactions that may be requested before the database open operation is completed
 - Report an error upon attempt to close a database handle object multiple times.
 
-## 1.0.5
+### 1.0.5
 
 - Workaround for Android db locking/closing issue
 - Fix double-precision REAL values in result (iOS version)
@@ -143,22 +139,22 @@
 - Fix closing of Android database
 - Some fixes for SQL API error handling to be consistent with Web SQL
 
-## 1.0.4
+### 1.0.4
 
 - Pre-populated database option (Android/iOS)
 - Option to select database location to disable iCloud backup (iOS ONLY)
 - Safeguard against closing of database while transaction is pending
 - Fix to prevent double marshaling of data
 
-## 1.0.3
+### 1.0.3
 
 - Fixed issue with multi-page apps on Android (due to problem when closing & re-opening app)
 
-## 1.0.2
+### 1.0.2
 
 - Workaround for issue with multiple UPDATE statements WP(8) (#128)
 
-## 1.0.1
+### 1.0.1
 
 - Support Cordova 3.3.0/3.4.0 to support Amazon-FireOS
 - Fixes for WP(8):

README.md

@@ -46,7 +46,7 @@ Use the `location` or `iosDatabaseLocation` option in `sqlitePlugin.openDatabase
 ## Status
 
 - A recent version of the Cordova CLI (such as `6.5.0`) is recommended. Cordova versions older than `6.0.0` are missing the `cordova-ios@4.0.0` security fixes. In addition it is *required* to use `cordova prepare` in case of cordova-ios older than `4.3.0` (Cordova CLI `6.4.0`).
-- iOS database location is now mandatory, as documented below.
+- The iOS database location is now mandatory, as documented below.
 - Android platform version in this version branch is now using the built-in Android SQLite database classes. Integration with the lightweight [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector) is available in the default [litehelpers / Cordova-sqlite-storage](https://github.com/litehelpers/Cordova-sqlite-storage) version branch as well as other versions such as [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) and [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy).
 - iOS/macOS platform version in this version branch uses builtin `libsqlite3.dylib` framework library. Other versions such as the default [litehelpers / Cordova-sqlite-storage](https://github.com/litehelpers/Cordova-sqlite-storage) version branch, [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext), and [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy) include a build of a recent sqlite3 amalgamation.
 - Windows 10 UWP version using the performant [doo / SQLite3-WinRT](https://github.com/doo/SQLite3-WinRT) component is available in the default [litehelpers / Cordova-sqlite-storage](https://github.com/litehelpers/Cordova-sqlite-storage) version branch as well as other versions such as [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext).
@@ -116,6 +116,32 @@ Use the `location` or `iosDatabaseLocation` option in `sqlitePlugin.openDatabase
 
 <!-- END Some apps using this plugin -->
 
+## Security
+
+### Security of sensitive data
+
+According to [Web SQL Database API 7.2 Sensitivity of data](https://www.w3.org/TR/webdatabase/#sensitivity-of-data):
+>User agents should treat persistently stored data as potentially sensitive; it's quite possible for e-mails, calendar appointments, health records, or other confidential documents to be stored in this mechanism.
+>
+>To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.
+
+Unfortunately this plugin will not actually overwrite the deleted content unless the [secure_delete PRAGMA](https://www.sqlite.org/pragma.html#pragma_secure_delete) is used.
+
+### SQL injection
+
+As "strongly recommended" by [Web SQL Database API 8.5 SQL injection](https://www.w3.org/TR/webdatabase/#sql-injection):
+>Authors are strongly recommended to make use of the `?` placeholder feature of the `executeSql()` method, and to never construct SQL statements on the fly.
+
+<!-- END Security -->
+
+# Avoiding data loss
+
+- Double-check that the application code follows the documented API for SQL statements, parameter values, success callbacks, and error callbacks.
+- For standard Web SQL transactions include a transaction error callback with the proper logic that indicates to the user if data cannot be stored for any reason. In case of individual SQL error handlers be sure to indicate to the user if there is any issue with storing data.
+- For single statement and batch transactions include an error callback with logic that indicates to the user if data cannot be stored for any reason.
+
+<!-- Avoiding data loss -->
+
 ## Known issues
 
 - iOS/macOS platform version does not support certain rapidly repeated open-and-close or open-and-delete test scenarios due to how the implementation handles background processing
@@ -176,36 +202,59 @@ Issues fixed in some newer version branches:
 - Integration with PhoneGap developer app
 - Use within [InAppBrowser](http://docs.phonegap.com/en/edge/cordova_inappbrowser_inappbrowser.md.html)
 - Use within an iframe (see [litehelpers/Cordova-sqlite-storage#368 (comment)](https://github.com/litehelpers/Cordova-sqlite-storage/issues/368#issuecomment-154046367))
+- Date/time handling
+- Maximum record size supported
 - Actual behavior when using SAVEPOINT(s)
 - R-Tree is not fully tested with Android
 - UNICODE characters not fully tested
 - Use with TRIGGER(s), JOIN and ORDER BY RANDOM
 - UPDATE/DELETE with LIMIT or ORDER BY (newer Android/iOS versions)
-- WITH clause (not supported by older sqlite3 versions)
 - Integration with JXCore for Cordova (must be built without sqlite(3) built-in)
 - Delete an open database inside a statement or transaction callback.
+- WITH clause (not supported by some older sqlite3 versions)
+- Handling of invalid transaction and transaction.executeSql arguments
+- Use of database locations on macOS
+- Extremely large and small INTEGER and REAL values ref: [litehelpers/Cordova-sqlite-storage#627](https://github.com/litehelpers/Cordova-sqlite-storage/issues/627))
+- More emojis and other 4-octet UTF-8 characters
+- `?NNN`/`:AAA`/`@AAAA`/`$AAAA` parameter placeholders ref: <https://www.sqlite.org/lang_expr.html#varparam>, <https://www.sqlite.org/c3ref/bind_blob.html>)
+- Single-statement and SQL batch transaction calls with invalid arguments (TBD behavior subject to change)
+
+<!-- END Further testing needed -->
 
 ## Some tips and tricks
 
 - If you run into problems and your code follows the asynchronous HTML5/[Web SQL](http://www.w3.org/TR/webdatabase/) transaction API, you can try opening a test database using `window.openDatabase` and see if you get the same problems.
 - In case your database schema may change, it is recommended to keep a table with one row and one column to keep track of your own schema version number. It is possible to add it later. The recommended schema update procedure is described below.
 
-## Common pitfall(s)
+<!-- END Some tips and tricks -->
+
+## Pitfalls
 
+### Some common pitfall(s)
+
+- If a database is opened using the standard `window.openDatabase` call it will not have any of the benefits of this plugin and features such as the `sqlBatch` call would not be available.
 - It is NOT allowed to execute sql statements on a transaction that has already finished, as described below. This is consistent with the HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/).
 - The plugin class name starts with "SQL" in capital letters, but in Javascript the `sqlitePlugin` object name starts with "sql" in small letters.
 - Attempting to open a database before receiving the 'deviceready' event callback.
 - Inserting STRING into ID field
 - Auto-vacuum is NOT enabled by default. It is recommended to periodically VACUUM the database.
+- Transactions on a database are run sequentially. A large transaction could block smaller transactions requested afterwards.
 
-## Weird pitfall(s)
+### Some weird pitfall(s)
 
 - intent whitelist: blocked intent such as external URL intent *may* cause this and perhaps certain Cordova plugin(s) to misbehave (see [litehelpers/Cordova-sqlite-storage#396](https://github.com/litehelpers/Cordova-sqlite-storage/issues/396))
 
-## Angular/ngCordova/Ionic-related pitfalls
+### Angular/ngCordova/Ionic-related pitfalls
 
 - Angular/ngCordova/Ionic controller/factory/service callbacks may be triggered before the 'deviceready' event is fired
 - As discussed in [litehelpers/Cordova-sqlite-storage#355](https://github.com/litehelpers/Cordova-sqlite-storage/issues/355), it may be necessary to install ionic-plugin-keyboard
+- Navigation items such as root page can be tricky on Ionic 2 ref: [litehelpers/Cordova-sqlite-storage#613](https://github.com/litehelpers/Cordova-sqlite-storage/issues/613)
+
+### General Cordova pitfalls
+
+Documented in: [brodybits / Avoiding-some-Cordova-pitfalls](https://github.com/brodybits/Avoiding-some-Cordova-pitfalls)
+
+<!-- END pitfalls -->
 
 ## Major TODOs
 
@@ -281,7 +330,9 @@ window.sqlitePlugin.selfTest(successCallback, errorCallback);
 
 ## General
 
-The idea is to emulate the HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/) as closely as possible. The only major change is to use `window.sqlitePlugin.openDatabase()` (or `sqlitePlugin.openDatabase()`) *with parameters as documented below* instead of `window.openDatabase()`. If you see any other major change please report it, it is probably a bug.
+- Drop-in replacement for HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/): the only change should be to replace the static `window.openDatabase()` factory call with `window.sqlitePlugin.openDatabase()`, with parameters as documented below. (Some known deviations are documented in newer version branches.)
+- Single-page application design is recommended.
+- In case of a multi-page application the JavaScript used by each page must use `sqlitePlugin.openDatabase` to open the database access handle object before it can access the data.
 
 **NOTE:** If a sqlite statement in a transaction fails with an error, the error handler *must* return `false` in order to recover the transaction. This is correct according to the HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/) standard. This is different from the WebKit implementation of Web SQL in Android and iOS which recovers the transaction if a sql error hander returns a non-`true` value.
 
@@ -730,9 +781,27 @@ The transactional nature of the API makes it relatively straightforward to manag
 
 ## Use with Ionic/ngCordova/Angular
 
-It is recommended to follow the tutorial at: https://blog.nraboy.com/2014/11/use-sqlite-instead-local-storage-ionic-framework/
+### Ionic 2
+
+Tutorials with Ionic 2:
+- <https://www.thepolyglotdeveloper.com/2016/08/using-sqlstorage-instead-sqlite-ionic-2-app/> (title is somewhat misleading, "SQL storage" *does* use this sqlite plugin)
+- <https://www.thepolyglotdeveloper.com/2015/12/use-sqlite-in-ionic-2-instead-of-local-storage/> (older tutorial)
+
+Sample for Ionic 2 wanted ref: [litehelpers/Cordova-sqlite-storage#585](https://github.com/litehelpers/Cordova-sqlite-storage/issues/585)
+
+### Ionic 1
+
+Tutorial with Ionic 1: <https://blog.nraboy.com/2014/11/use-sqlite-instead-local-storage-ionic-framework/>
+
+A sample for Ionic 1 is provided at: [litehelpers / Ionic-sqlite-database-example](https://github.com/litehelpers/Ionic-sqlite-database-example)
+
+Documentation at: <http://ngcordova.com/docs/plugins/sqlite/>
+
+Other resource (apparently for Ionic 1): <https://www.packtpub.com/books/content/how-use-sqlite-ionic-store-data>
+
+**NOTE:** Some Ionic and other Angular pitfalls are described above.
 
-Documentation at: http://ngcordova.com/docs/plugins/sqlite/
+<!-- END Use with Ionic/ngCordova/Angular -->
 
 # Installing
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-sqlite-legacy-express-core",
-  "version": "1.0.0-pre4",
+  "version": "1.0.0",
   "description": "Native interface to SQLite for PhoneGap/Cordova (legacy express core version)",
   "cordova": {
     "id": "cordova-sqlite-legacy-express-core",

plugin.xml

@@ -2,7 +2,7 @@
 <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
     xmlns:android="http://schemas.android.com/apk/res/android"
     id="cordova-sqlite-legacy-express-core"
-    version="1.0.0-pre4">
+    version="1.0.0">
 
     <name>Cordova sqlite storage plugin - legacy express core version</name>