From f2406f5d25457a53e25922f2f68419ef416a5645 Mon Sep 17 00:00:00 2001 From: "Christopher J. Brody" Date: Sun, 19 Nov 2017 17:46:57 -0500 Subject: [PATCH] README.md doc fixes --- README.md | 53 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 24c3df237..298f0463d 100644 --- a/README.md +++ b/README.md @@ -101,10 +101,9 @@ Use the `location` or `iosDatabaseLocation` option in `sqlitePlugin.openDatabase - INCORRECT error code and INCONSISTENT error message in error callbacks ref: [litehelpers/Cordova-sqlite-storage#539](https://github.com/litehelpers/Cordova-sqlite-storage/issues/539) - Not possible to read BLOB column values - Windows platform version uses `UTF-16le` internal database encoding while the other platform versions use `UTF-8` internal encoding. (`UTF-8` internal encoding is preferred ref: [litehelpers/Cordova-sqlite-storage#652](https://github.com/litehelpers/Cordova-sqlite-storage/issues/652)) -- FTS3, FTS4, and R-Tree support is tested working OK in this version (for all target platforms in this version branch Android/iOS/macOS/Windows) - Android versions supported: 2.3.3 - 7.1.1 (API level 10 - 25), depending on Cordova version ref: -minimum API level is supported back to SDK 10 (a.k.a. Gingerbread, Android 2.3.3); support for older versions is available upon request. - iOS versions supported: 8.x / 9.x / 10.x / 11.x +- FTS3, FTS4, and R-Tree support is tested in this version branch for all target platforms Android/iOS/macOS/Windows. - In case of memory issues please use smaller transactions or use the version at [litehelpers / Cordova-sqlite-evcore-extbuild-free](https://github.com/litehelpers/Cordova-sqlite-evcore-extbuild-free) (GPL or commercial license terms). @@ -126,7 +125,7 @@ minimum API level is supported back to SDK 10 (a.k.a. Gingerbread, Android 2.3.3 - Android version currently uses the lightweight [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector) by default configuration (may be changed as described below). - Self-test functions to verify proper installation and operation of this plugin - More explicit `openDatabase` and `deleteDatabase` `iosDatabaseLocation` option -- Added simple sql batch function +- Added straightforward sql batch function - [MetaMemoryT / websql-promise](https://github.com/MetaMemoryT/websql-promise) now provides a Promises-based interface to both Web SQL and this plugin - [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android/iOS/macOS/Windows is supported by [litehelpers / Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter) @@ -205,10 +204,9 @@ As "strongly recommended" by [Web SQL Database API 8.5 SQL injection](https://ww - Close/delete database bugs described below. - When a database is opened and deleted without closing, the iOS/macOS platform version is known to leak resources. - It is NOT possible to open multiple databases with the same name but in different locations (iOS/macOS platform version). -- Incorrect or missing insertId/rowsAffected in results for INSERT/UPDATE/DELETE SQL statements with extra semicolon(s) in the beginning for Android (android.database implementation) -- readTransaction does *not* reject modification SQL statements with extra semicolon(s) in the beginning Issues fixed in some newer version branches: +- Incorrect or missing insertId/rowsAffected in results for INSERT/UPDATE/DELETE SQL statements with extra semicolon(s) in the beginning for Android platform version in case the `androidDatabaseImplementation: 2` (built-in android.database implementation) option is used. - In case of an error, the error `code` member is bogus on Android - iOS platform version generates extra logging in release version - iOS platform version may crash if deleteDatabase is called with an object in place of the database name @@ -217,6 +215,8 @@ Issues fixed in some newer version branches: - extra executeSql callbacks triggered in a transaction after a failure that was not recovered by an error callback that returns false - does not signal an error in case of excess parameter argument values given on iOS/macOS +Some additional issues are tracked in [open Cordova-sqlite-storage bug-general issues](https://github.com/litehelpers/Cordova-sqlite-storage/issues?q=is%3Aissue+is%3Aopen+label%3Abug-general). + ## Other limitations @@ -229,7 +229,6 @@ Issues fixed in some newer version branches: - In-memory database `db=window.sqlitePlugin.openDatabase({name: ':memory:', ...})` is currently not supported. - The Android platform version cannot properly support more than 100 open database files due to the threading model used. - SQL error messages reported by Windows platform version are not consistent with Android/iOS/macOS platform versions. -- UNICODE `\u2028` (line separator) and `\u2029` (paragraph separator) characters are not supported and known to be broken on iOS, macOS, and Android platform versions due to JSON issues reported in [Cordova bug CB-9435](https://issues.apache.org/jira/browse/CB-9435) and [cordova/cordova-discuss#57](https://github.com/cordova/cordova-discuss/issues/57). - UNICODE `\u2028` (line separator) and `\u2029` (paragraph separator) characters are currently not supported and known to be broken on iOS, macOS, and Android platform versions due to JSON issues reported in [Cordova bug CB-9435](https://issues.apache.org/jira/browse/CB-9435) and [cordova/cordova-discuss#57](https://github.com/cordova/cordova-discuss/issues/57). This is fixed with a workaround for iOS/macOS in: [litehelpers / Cordova-sqlite-evplus-legacy-free](https://github.com/litehelpers/Cordova-sqlite-evplus-legacy-free) and [litehelpers / Cordova-sqlite-evplus-legacy-attach-detach-free](https://github.com/litehelpers/Cordova-sqlite-evplus-legacy-attach-detach-free) (available with GPL or special commercial license options) as well as [litehelpers / Cordova-sqlite-evplus-legacy-workers-free](https://github.com/litehelpers/Cordova-sqlite-evplus-legacy-workers-free) (available with GPL or premium commercial license options) - The BLOB data type is not fully supported by this version branch. SELECT BLOB in Base64 format is supported by [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) (permissive license terms) and [litehelpers / Cordova-sqlite-evcore-extbuild-free](https://github.com/litehelpers/Cordova-sqlite-evcore-extbuild-free) (GPL or commercial license options). - Truncation in case of UNICODE `\u0000` (same as `\0`) character on Android (default Android-sqlite-connector database implementation) and Windows. @@ -243,6 +242,8 @@ Issues fixed in some newer version branches: - Problems have been reported when using this plugin with Crosswalk (for Android). It may help to install Crosswalk as a plugin instead of using Crosswalk to create the project. - Does not work with [axemclion / react-native-cordova-plugin](https://github.com/axemclion/react-native-cordova-plugin) since the `window.sqlitePlugin` object is *not* properly exported (ES5 feature). It is recommended to use [andpor / react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage) for SQLite database access with React Native Android/iOS instead. +Additional limitations are tracked in [open Cordova-sqlite-storage doc-todo issues](https://github.com/litehelpers/Cordova-sqlite-storage/issues?q=is%3Aissue+is%3Aopen+label%3Adoc-todo). + ## Further testing needed @@ -255,7 +256,7 @@ Issues fixed in some newer version branches: - 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 +- ORDER BY RANDOM() (ref: [litehelpers/Cordova-sqlite-storage#334](https://github.com/litehelpers/Cordova-sqlite-storage/issues/334)) - UPDATE/DELETE with LIMIT or ORDER BY (newer Android/iOS versions) - Integration with JXCore for Cordova (must be built without sqlite(3) built-in) - Delete an open database inside a statement or transaction callback. @@ -306,12 +307,22 @@ Documented in: [brodybits / Avoiding-some-Cordova-pitfalls](https://github.com/b ## Major TODOs -- Integrate with IndexedDBShim and some other libraries such as Sequelize, Squel.js, WebSqlSync, Persistence.js, Knex, etc. +- More formal documentation of API, especially for non-standard functions +- Browser platform +- IndexedDBShim adapter +- Further cleanup of [support](#support) section +- Resolve or document remaining [open Cordova-sqlite-storage bugs](https://github.com/litehelpers/Cordova-sqlite-storage/issues?q=is%3Aissue+is%3Aopen+label%3Abug-general) +- Resolve [cordova-sqlite-help doc-todo issues](https://github.com/litehelpers/Cordova-sqlite-help/issues?q=is%3Aissue%20label%3Adoc-todo) and [cordova-sqlite-storage doc-todo issues](https://github.com/litehelpers/Cordova-sqlite-storage/issues?q=is%3Aissue+is%3Aopen+label%3Adoc-todo) + + ## For future considertion - Auto-vacuum option -- Browser platform +- Support for extremely large records in a version such as [litehelpers / Cordova-sqlite-evcore-extbuild-free](https://github.com/litehelpers/Cordova-sqlite-evcore-extbuild-free) (available with GPL or commercial license options) +- Integrate with some other libraries such as Sequelize, Squel.js, WebSqlSync, Persistence.js, Knex, etc. + + ## Alternatives @@ -901,6 +912,18 @@ cordova platform add ios +## Windows platform usage notes + +This plugin is not 100% intuitive to use on Windows since it includes a native SQLite3 library that is built as a part of the Cordova app. Here are some requirements: + +- It is **not** possible to use this plugin with the default "Any CPU" target. A specific CPU target must be selected. +- It is **not** allowed to manually change the app id in the Windows platform. The Windows app ID may be declared: + - using a `windows-identity-name` attribute (ref: ); + - "WindowsStoreIdentityName" setting (ref: ). +- Proper C++ library support is needed from Visual Studio. This may need some additional Visual Studio components to be installed. + + + ## Source tree - `SQLitePlugin.coffee.md`: platform-independent (Literate coffee-script, can be read by recent coffee-script compiler) @@ -939,7 +962,7 @@ Free support is provided on a best-effort basis and is only available in public Commercial support is available by contacting: -## Before asking for help +## Before seeking help First steps: - Verify that you have followed the steps in [brodybits / Cordova-quick-start-checklist](https://github.com/brodybits/Cordova-quick-start-checklist) @@ -980,7 +1003,7 @@ Free support for issues with Angular/"ngCordova"/Ionic will only be provided if ## What information is needed for help Please include the following: -- Which platform(s) _(Android/iOS/macOS/Windows 8.1/Windows Phone 8.1/Windows 10)_ +- Which platform(s) (Android/iOS/macOS/Windows 8.1/Windows Phone 8.1/Windows 10) - Clear description of the issue - A small, complete, self-contained program that demonstrates the problem, preferably as a Github project. ZIP/TGZ/BZ2 archive available from a public link is OK. No RAR or other such formats please! - A Cordova project is highly preferred. Intel, MS IDE, or similar project formats should be avoided. @@ -1025,6 +1048,8 @@ To run from a windows powershell (here is a sample for android target): # Adapters +**GENERAL:** The adapters described here are community maintained. + ## Lawnchair Adapter - [litehelpers / cordova-sqlite-lawnchair-adapter](https://github.com/litehelpers/cordova-sqlite-lawnchair-adapter) @@ -1033,6 +1058,12 @@ To run from a windows powershell (here is a sample for android target): - [nolanlawson / pouchdb-adapter-cordova-sqlite](https://github.com/nolanlawson/pouchdb-adapter-cordova-sqlite) +## Adapters wanted + +- IndexedDBShim adapter + + + # Contributing ## Community