From d2a35dac5fcd202a1ccd30482a7edc37f0e9bdff Mon Sep 17 00:00:00 2001 From: "Christopher J. Brody" Date: Sun, 7 Feb 2016 22:46:30 +0100 Subject: [PATCH] Prepare to publish (0.8.0-pre) Fix CHANGES.md & HISTORY.md Update README.md Mark version in package.json & plugin.xml --- CHANGES.md | 118 +++++++++++++++++++- HISTORY.md | 9 +- README.md | 308 ++++++++++++++++++--------------------------------- package.json | 22 ++-- plugin.xml | 8 +- 5 files changed, 239 insertions(+), 226 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index ca0a0c90d..b1c577a6c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,25 +1,133 @@ # Changes -## 0.x.x-xx +## 0.8.0-pre - 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 -- Move Android version to io.sqlc package +- Java source of Android version now using io.sqlc package -## 0.7.2-common-dev +## 0.7.15-pre - All iOS operations are now using background processing (reported to resolve intermittent problems with cordova-ios@4.0.1) -## 0.7.1-common-dev +## 0.7.14 -- REGEXP support removed from this version branch +- REGEXP support completely removed from this version branch +- Remove src/android/libs/.gitignore (inadvertently added in 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 +- Android version with sqlite `3.8.10.2` embedded (with error messages fixed) - Pre-populated database support removed from this version branch - Amazon Fire-OS support removed - Fix conversion warnings in iOS version + +## 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 + +- 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 due to https://issues.apache.org/jira/browse/CB-9638 + +## 0.7.10 + +- Use Android-sqlite-connector instead of sqlite4java + +## 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 + +- 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 + +- include build of sqlite4java for Android x86_64 and arm-64 +- clean publish to plugins.cordova.io + +## 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 + +- 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 + +- 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 + +- insertId & rowsAffected implemented for Windows (8.1) +- plugin id changed + +## 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 + +- 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 + +- 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 + +- Workaround for Android db locking/closing issue +- Fix double-precision REAL values in result (iOS version) +- Fix query result truncation in case of NULL character (\0 or \u0000) (iOS version) +- Convert array SQL parameters to string, according to match Web SQL spec +- Fix closing of Android database +- Some fixes for SQL API error handling to be consistent with Web SQL + +## 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 + +- Fixed issue with multi-page apps on Android (due to problem when closing & re-opening app) + +## 1.0.2 + +- Workaround for issue with multiple UPDATE statements WP(8) (#128) + +## 1.0.1 + +- Support Cordova 3.3.0/3.4.0 to support Amazon-FireOS +- Fixes for WP(8): + - use one thread per db to solve open/close/delete issues + - fix integer data binding +- Fix open/close callbacks Android & WP(8) +- Resolve issue with INSERT OR IGNORE (Android) diff --git a/HISTORY.md b/HISTORY.md index 064ec9f44..2eb3ec957 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -122,8 +122,13 @@ Other major changes by @brodybits in 2015: ## Major changes 2016 -- Windows version removed from this version branch (available in cordova-sqlite-ext or Cordova-sqlite-legacy versions) -- Android-sqlite-connector (NDK) support removed from this version branch (available in cordova-sqlite-ext or Cordova-sqlite-legacy versions) +Features removed from main version branch, available in cordova-sqlite-ext and Cordova-sqlite-legacy versions: +- Windows version removed from this version branch +- Android-sqlite-connector (NDK) support removed from this version branch + +New features: +- Echo self-test function +- Simple sql batch query interface ## Recent changes diff --git a/README.md b/README.md index b6a8f634a..58887d67d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ -# Cordova/PhoneGap sqlite storage adapter (common-src branch) +# Cordova/PhoneGap sqlite storage adapter (core version) -Native interface to sqlite in a Cordova/PhoneGap plugin for Android, _and_ iOS, ~~and Windows "Universal" (8.1),~~ with API similar to HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/). +Native interface to sqlite in a Cordova/PhoneGap plugin for Android and iOS, with API similar to HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/). -License for Android ~~and Windows "Universal" (8.1)~~ version~~s~~: MIT or Apache 2.0 +License for Android version: MIT or Apache 2.0 License for iOS version: MIT only -This version branch contains the source code for the Android, iOS~~, and Windows "Universal" (8.1)~~ versions. This version branch does not contain any libraries or source code from www.sqlite.org. This version branch uses the built-in sqlite libraries on Android and iOS. +This version contains the source code for the Android and iOS versions. This version does not contain any libraries or source code from www.sqlite.org. This version uses the built-in sqlite libraries on Android and iOS. -NOTE (TBD): no Circle CI or Travis CI working in this version branch. +|Android CI (~~full~~ limited suite)|iOS CI (limited suite)| +|-----------------------|----------------------| +|[![Circle CI](https://circleci.com/gh/litehelpers/Cordova-sqlite-storage.svg?style=svg)](https://circleci.com/gh/litehelpers/Cordova-sqlite-storage)|[![Build Status](https://travis-ci.org/litehelpers/Cordova-sqlite-storage.svg?branch=master-rc)](https://travis-ci.org/litehelpers/Cordova-sqlite-storage)| ## IMPORTANT: iCloud backup of SQLite database is NOT allowed @@ -34,29 +36,27 @@ As documented in the "**A User’s iCloud Storage Is Limited**" section of [iClo ### More information about iCloud backup There are two ways iCloud backup is configured: -- For each app, iCloud backup is configured in `config.xml` **and is enabled by default** (which I think is wrong) as documented at: https://cordova.apache.org/docs/en/5.1.1/guide/platforms/ios/config.html +- For each app, iCloud backup is configured in `config.xml` and is *unfortunately* **enabled by default** as documented at: https://cordova.apache.org/docs/en/6.0.0/guide/platforms/ios/config.html - In this plugin, the database is stored in the `Documents` subdirectory by default, which is backed up to iCloud. You can use the `location` option in `sqlitePlugin.openDatabase()` to store the database in a subdirectory that is *NOT* backed up to iCloud. -Unless you want your app to use iCloud backup for some reason, it is recommended to turn it off as documented in: https://cordova.apache.org/docs/en/5.1.1/guide/platforms/ios/config.html +Unless you want your app to use iCloud backup for some reason, it is recommended to turn it off as documented in: https://cordova.apache.org/docs/en/6.0.0/guide/platforms/ios/config.html -I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to disable iCloud backup by default in `config.xml`. +[@brodybits](https://github.com/brodybits) reported [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to disable iCloud backup by default in `config.xml`. + +## Support this project + +[@brodybits (Christopher J. Brody aka Chris Brody)](https://github.com/brodybits) dedicates a significant amout of working time to maintain and improve this project, and has turned down multiple full-time work opportunities in order to support this project. [@brodybits](https://github.com/brodybits) is available for part-time work in areas related to this project including priority support, priority feature development, and higher-level application development. Such part-time assignments would help [@brodybits](https://github.com/brodybits) keep this project alive. ## Status -- Android version in this version branch is now using the built-in SQLite database classes. -- Windows "Universal" version is removed from this version branch. -- WP(7/8) is not supported by this version branch (TBD link to where WP(7/8) will be supported) +- Android 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 [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) and [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy). +- Windows 8.1/Windows Phone 8.1 version is removed from this project, available in [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) and [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy). +- WP(7/8) is not supported by this version branch, moved to [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy). - The following features are moved to [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) and removed from this project: - REGEXP support - Pre-populated database - Amazon Fire-OS is dropped due to lack of support by Cordova. Android version should be used to deploy to Fire-OS 5.0(+) devices ref: [cordova/cordova-discuss#32 (comment)](https://github.com/cordova/cordova-discuss/issues/32#issuecomment-167021676) -- ~~Windows "Universal" for Windows 8.0/8.1(+) and Windows Phone 8.1(+) version is in an alpha state:~~ - - ~~Issue with UNICODE `\u0000` character (same as `\0`)~~ - - ~~No background processing (for future consideration)~~ - - ~~You *may* encounter issues with Cordova CLI due to [CB-8866](https://issues.apache.org/jira/browse/CB-8866). *Old workaround:* you can install using [litehelpers / cordova-windows-nufix](https://github.com/litehelpers/cordova-windows-nufix) and `plugman` as described below.~~ - - ~~In addition, problems with the Windows "Universal" version have been reported in case of a Cordova project using a Visual Studio template/extension instead of Cordova/PhoneGap CLI or `plugman`~~ - - ~~Not tested with a Windows 10 (or Windows Phone 10) target; Windows 10 build is not expected to work with Windows Phone~~ -- FTS3, FTS4, and R-Tree support is tested working OK in this version (for all target platforms in this version branch Android/iOS/Windows "Universal") +- FTS3, FTS4, and R-Tree support is tested working OK in this version (for all target platforms in this version branch Android/iOS) - Android is supported back to SDK 10 (a.k.a. Gingerbread, Android 2.3.3); support for older versions is available upon request. - API to open the database may be changed somewhat to be more streamlined. Transaction and single-statement query API will NOT be changed. - In case of memory issues please use smaller transactions or use the version (with a different licensing scheme) at: [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free) or [litehelpers / cordova-sqlite-workers-evfree](https://github.com/litehelpers/cordova-sqlite-workers-evfree) @@ -65,17 +65,16 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to - Added simple sql batch query function - Added echo test function to verify installation of this plugin +- Published [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy) for maintenance of WP(7/8) version, working with the other supported platforms Android/iOS/Windows 8.1(+)/Windows Phone 8.1(+) - All iOS operations are now using background processing (reported to resolve intermittent problems with cordova-ios@4.0.1) - Published [brodybits / Cordova-quick-start-checklist](https://github.com/brodybits/Cordova-quick-start-checklist) and [brodybits / Cordova-troubleshooting-guide](https://github.com/brodybits/Cordova-troubleshooting-guide) - A version with support for web workers is available (with a different licensing scheme) at: [litehelpers / cordova-sqlite-workers-evfree](https://github.com/litehelpers/cordova-sqlite-workers-evfree) - A version with pre-populated database support added for Windows "Universal" and REGEXP support added for Android is available at: [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) - PhoneGap Build is now supported through the npm package: http://phonegap.com/blog/2015/05/26/npm-plugins-available/ - [MetaMemoryT / websql-promise](https://github.com/MetaMemoryT/websql-promise) now provides a Promises-based interface to both Web SQL and this plugin -- REMOVED from this version branch: ~~Android version is now using the lightweight [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector) by default configuration (may be changed as described below)~~ - iOS version is now fixed to override the correct pluginInitialize method and should work with recent versions of iOS - [SQLCipher](https://www.zetetic.net/sqlcipher/) for Windows (8.1) in addition to Android & iOS is now supported by [litehelpers / Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter) - New `openDatabase` and `deleteDatabase` `location` option to select database location (iOS *only*) and disable iCloud backup -- Fixes to work with PouchDB by [@nolanlawson](https://github.com/nolanlawson) ## Highlights @@ -97,11 +96,11 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to - iOS version does not support certain rapidly repeated open-and-close or open-and-delete test scenarios due to how the implementation handles background processing - As described below, auto-vacuum is NOT enabled by default. -- INSERT statement that affects multiple rows (due to SELECT cause or using TRIGGER(s), for example) does not report proper rowsAffected on Android ~~in case [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector) is disabled (using the `androidDatabaseImplementation` option in `window.sqlitePlugin.openDatabase`)~~ +- INSERT statement that affects multiple rows (due to SELECT cause or using TRIGGER(s), for example) does not report proper rowsAffected on Android - Memory issue observed when adding a large number of records due to the JSON implementation which is improved in [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free) (available with a different licensing scheme) - A stability issue was reported on the iOS version when in use together with [SockJS](http://sockjs.org/) client such as [pusher-js](https://github.com/pusher/pusher-js) at the same time (see [litehelpers/Cordova-sqlite-storage#196](https://github.com/litehelpers/Cordova-sqlite-storage/issues/196)). The workaround is to call sqlite functions and [SockJS](http://sockjs.org/) client functions in separate ticks (using setTimeout with 0 timeout). - If a sql statement fails for which there is no error handler or the error handler does not return `false` to signal transaction recovery, the plugin fires the remaining sql callbacks before aborting the transaction. -- In case of an error, the error `code` member is bogus on Android ~~and Windows~~ (fixed for Android in [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free)). +- In case of an error, the error `code` member is bogus on Android (fixed for Android in [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free)). - Possible crash on Android when using Unicode emoji characters due to [Android bug 81341](https://code.google.com/p/android/issues/detail?id=81341), which _should_ be fixed in Android 6.x - In-memory database `db=window.sqlitePlugin.openDatabase({name: ":memory:"})` is currently not supported. - Close database bugs described below. @@ -109,28 +108,24 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to - It is NOT possible to open multiple databases with the same name but in different locations (iOS version). - Problems reported with PhoneGap Build in the past: - PhoneGap Build Hydration. - - For some reason, PhoneGap Build may fail to build the iOS version unless the name of the app starts with an uppercase and contains no spaces (see [#243](https://github.com/litehelpers/Cordova-sqlite-storage/issues/243); [Wizcorp/phonegap-facebook-plugin#830](https://github.com/Wizcorp/phonegap-facebook-plugin/issues/830); [phonegap/build#431](https://github.com/phonegap/build/issues/431)). + - Apparently FIXED: ~~PhoneGap Build may fail to build the iOS version unless the name of the app starts with an uppercase and contains no spaces (see [litehelpers/Cordova-sqlite-storage#243](https://github.com/litehelpers/Cordova-sqlite-storage/issues/243); [Wizcorp/phonegap-facebook-plugin#830](https://github.com/Wizcorp/phonegap-facebook-plugin/issues/830); [phonegap/build#431](https://github.com/phonegap/build/issues/431)).~~ ## Other limitations - The db version, display name, and size parameter values are not supported and will be ignored. - This plugin will not work before the callback for the 'deviceready' event has been fired, as described in **Usage**. (This is consistent with the other Cordova plugins.) -- This version will not work within a web worker since are not supported by the Cordova framework. +- This version will not work within a web worker (not properly supported by the Cordova framework). - In-memory database `db=window.sqlitePlugin.openDatabase({name: ":memory:"})` is currently not supported. - The Android version cannot work with more than 100 open db files (due to the threading model used). -- UNICODE line separator (`\u2028`) and paragraph separator (`\u2029`) are currently not supported and known to be broken in iOS version due to [Cordova bug CB-9435](https://issues.apache.org/jira/browse/CB-9435). +- UNICODE line separator (`\u2028`) and paragraph separator (`\u2029`) are currently not supported and known to be broken in iOS version due to [Cordova bug CB-9435](https://issues.apache.org/jira/browse/CB-9435). There *may* be a similar issue with other UNICODE characters in the iOS version (needs further investigation). This is fixed in: [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free) (available with a different licensing scheme) - Blob type is currently not supported and known to be broken on multiple platforms. -- ~~Not a problem in this version branch: UNICODE `\u0000` (same as `\0`) character not working in Android (default native database implementation), Windows "Universal" (8.1/XX), or WP(7/8)~~ - Case-insensitive matching and other string manipulations on Unicode characters, which is provided by optional ICU integration in the sqlite source and working with recent versions of Android, is not supported for any target platforms. - iOS version uses a thread pool but with only one thread working at a time due to "synchronized" database access - Large query result can be slow, also due to JSON implementation -- ATTACH another database file is not supported (due to path specifications, which work differently depending on the target platform) +- ATTACH to another database file is not supported (due to path specifications, which work differently depending on the target platform) - User-defined savepoints are not supported and not expected to be compatible with the transaction locking mechanism used by this plugin. In addition, the use of BEGIN/COMMIT/ROLLBACK statements is not supported. -- Problems have been reported when using this plugin with Crosswalk (for Android). A couple of things you can try: - - Install Crosswalk as a plugin instead of using Crosswalk to create the project. - - Use `androidDatabaseImplementation: 2` in the openDatabase options as described below. +- 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 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. -- ~~_In another version branch:_ FTS3/FTS4 and R-Tree are NOT supported for WP(7/8)~~ ## Further testing needed @@ -138,7 +133,7 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to - 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)) - SAVEPOINT(s) -- R-Tree is not tested for all older releases of Android in case [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector) is disabled (using the `androidDatabaseImplementation` option in `window.sqlitePlugin.openDatabase`) +- R-Tree is not tested with some older releases of Android - UNICODE characters not fully tested - Use with TRIGGER(s), JOIN and ORDER BY RANDOM - Integration with JXCore for Cordova (must be built without sqlite(3) built-in) @@ -152,7 +147,6 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to ## Common pitfall(s) - It is NOT allowed to execute sql statements on a transaction following the HTML5/[Web SQL API](http://www.w3.org/TR/webdatabase/), as described below. -- ~~Not in this version branch: It is possible to make a Windows Phone 8.1 project using either the `windows` platform or the `wp8` platform. The `windows` platform is highly recommended over `wp8` whenever possible. Also, some plugins only support `windows` and some plugins support only `wp8`.~~ - 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 @@ -175,10 +169,11 @@ I raised [Cordova bug CB-9830](https://issues.apache.org/jira/browse/CB-9830) to ### Other versions +- [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) - version with REGEXP support Android/iOS and pre-populated database support *added* for Windows 8.1(+)/Windows Phone 8.1(+) +- [litehelpers / Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter) - supports [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android, iOS, and Windows 8.1(+)/Windows Phone 8.1(+) +- [litehelpers / Cordova-sqlite-legacy](https://github.com/litehelpers/Cordova-sqlite-legacy) - maintenance of WP(7/8) version-working with the other supported platforms Android/iOS/Windows 8.1(+)/Windows Phone 8.1(+) - [litehelpers / Cordova-sqlite-enterprise-free](https://github.com/litehelpers/Cordova-sqlite-enterprise-free) - internal memory improvements to support larger transactions (Android/iOS) and fix to support all Unicode characters (iOS) - with a different licensing scheme - [litehelpers / cordova-sqlite-workers-evfree](https://github.com/litehelpers/cordova-sqlite-workers-evfree) - version with support for web workers, includes internal memory improvements to support larger transactions (Android/iOS) and fix to support all Unicode characters (iOS) - with a different licensing scheme -- [litehelpers / cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext) - version with REGEXP support *added* for Android and pre-populated database support *added* for Windows "Universal" as well -- [litehelpers / Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter) - supports [SQLCipher](https://www.zetetic.net/sqlcipher/) for Android, iOS, and Windows (8.1) - Adaptation for React Native Android and iOS: [andpor / react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage) - Original version for iOS (with a slightly different transaction API): [davibe / Phonegap-SQLitePlugin](https://github.com/davibe/Phonegap-SQLitePlugin) @@ -213,7 +208,7 @@ To verify that both the Javascript and native part of this plugin are installed window.sqlitePlugin.echoTest(successCallback, errorCallback); ``` -**IMPORTANT:** Please wait for the 'deviceready' event, (see below for an example). +**IMPORTANT:** Please wait for the 'deviceready' event (see below for an example). ## General @@ -264,21 +259,9 @@ If any sql statements or transactions are attempted on a database object before - It is possible to open multiple database access objects for the same database. - The database access object can be closed as described below. -### Android sqlite implementation - -REMOVED from this version branch - -~~By default, this plugin uses [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector), which is lightweight and should be more efficient than the built-in Android database classes. To use the built-in Android database classes instead:~~ - -IGNORED in this version branch: - -```js -var db = window.sqlitePlugin.openDatabase({name: "my.db", androidDatabaseImplementation: 2}); -``` - ### Workaround for Android db locking issue -[Issue #193](https://github.com/litehelpers/Cordova-sqlite-storage/issues/193) was reported (as observed by several app developers) that on some newer versions of the Android database classes, if the app is stopped or aborted without closing the database then: +[litehelpers/Cordova-sqlite-storage#193](https://github.com/litehelpers/Cordova-sqlite-storage/issues/193) was reported (as observed by several app developers) that on some newer versions of the Android database classes, if the app is stopped or aborted without closing the database then: - (sometimes) there is an unexpected database lock - the data that was inserted is lost. @@ -287,11 +270,9 @@ This issue is suspected to be caused by [this Android sqlite commit](https://git There is an optional workaround that simply closes and reopens the database file at the end of every transaction that is committed. The workaround is enabled by opening the database with options as follows: ```js -var db = window.sqlitePlugin.openDatabase({name: "my.db", androidDatabaseImplementation: 2, androidLockWorkaround: 1}); +var db = window.sqlitePlugin.openDatabase({name: 'my.db', androidLockWorkaround: 1}); ``` -This option is ignored if `androidDatabaseImplementation: 2` is not specified. - **IMPORTANT NOTE:** This workaround is *only* applied when using `db.transaction()`, *not* applied when running `executeSql()` on the database object. ## SQL transactions @@ -403,12 +384,11 @@ You can find more details and a step-by-step description how to do this right in The threading model depends on which version is used: - For Android, one background thread per db; -- for iOS, background processing using a very limited thread pool (only one thread working at a time); -- ~~for Windows "Universal" (8.1), no background processing (for future consideration).~~ +- for iOS, background processing using a very limited thread pool (only one thread working at a time). -# Sample with PRAGMA feature +## Sample with PRAGMA feature -This is a pretty strong test: first we create a table and add a single entry, then query the count to check if the item was inserted as expected. Note that a new transaction is created in the middle of the first callback. +Creates a table, adds a single entry, then queries the count to check if the item was inserted as expected. Note that a new transaction is created in the middle of the first callback. ```js // Wait for Cordova to load @@ -553,8 +533,6 @@ window.sqlitePlugin.deleteDatabase({name: "my.db", location: 1}, successcb, erro `location` as described above for `openDatabase` (iOS *only*) -FIXED: ~~**NOTE:** not implemented for Windows "Universal" (8.1) version.~~ - # Schema versions The transactional nature of the API makes it relatively straightforward to manage a database schema that may be upgraded over time (adding new columns or new tables, for example). Here is the recommended procedure to follow upon app startup: @@ -577,12 +555,10 @@ Documentation at: http://ngcordova.com/docs/plugins/sqlite/ npm install -g cordova # if you don't have cordova cordova create MyProjectFolder com.my.project MyProject && cd MyProjectFolder # if you are just starting - cordova plugin add https://github.com/litehelpers/cordova-sqlite-common + cordova plugin add https://github.com/litehelpers/Cordova-sqlite-storage You can find more details at [this writeup](http://iphonedevlog.wordpress.com/2014/04/07/installing-chris-brodys-sqlite-database-with-cordova-cli-android/). -~~**WARNING:** for Windows target platform please read the section above.~~ - **IMPORTANT:** sometimes you have to update the version for a platform before you can build, like: `cordova prepare ios` **NOTE:** If you cannot build for a platform after `cordova prepare`, you may have to remove the platform and add it again, such as: @@ -593,103 +569,29 @@ You can find more details at [this writeup](http://iphonedevlog.wordpress.com/20 ## Easy install with plugman tool ```shell -plugman install --platform MYPLATFORM --project path.to.my.project.folder --plugin https://github.com/litehelpers/cordova-sqlite-common +plugman install --platform MYPLATFORM --project path.to.my.project.folder --plugin https://github.com/litehelpers/Cordova-sqlite-storage ``` where MYPLATFORM is `android`, `ios`~~, or `windows`~~. A posting how to get started developing on Windows host without the Cordova CLI tool (for Android target only) is available [here](http://brodybits.blogspot.com/2015/03/trying-cordova-for-android-on-windows-without-cordova-cli.html). +## Installation sources + +- https://github.com/litehelpers/Cordova-sqlite-storage - latest version +- `cordova-sqlite-storage` - stable npm package version + ## Source tree - `SQLitePlugin.coffee.md`: platform-independent (Literate coffee-script, can be read by recent coffee-script compiler) - `www`: `SQLitePlugin.js` platform-independent Javascript as generated from `SQLitePlugin.coffee.md` (and checked in!) - `src`: platform-specific source code: - - ~~REMOVED from this version branch: `external` - placeholder used to import `sqlite3.[hc]` in this version branch-needed to build Windows "Universal" (8.1) version~~ - `android` - Java plugin code for Android - `ios` - Objective-C plugin code for iOS; - - ~~`windows` - Javascript proxy code and SQLite3-WinRT project for Windows "Universal" (8.1);~~ -- `spec`: test suite using Jasmine (2.2.0), ported from QUnit `test-www` test suite, working on all platforms -- `tests`: very simple Jasmine test suite that is run on Circle CI (Android version) and Travis CI (iOS version) +- `spec`: test suite using Jasmine (2.2.0) +- `tests`: very simple Jasmine test suite that is run on Circle CI (Android version) and Travis CI (iOS version) (used as a placeholder) - `Lawnchair-adapter`: Lawnchair adaptor, based on the version from the Lawnchair repository, with the basic Lawnchair test suite in `test-www` subdirectory -## Manual installation - Android version - -These installation instructions are based on the Android example project from Cordova/PhoneGap 2.7.0, using the `lib/android/example` subdirectory from the PhoneGap 2.7 zipball. - - - Install `SQLitePlugin.js` from `www` into `assets/www` - - Install `SQLitePlugin.java` from `src/android/io/liteglue` into `src/io/liteglue` subdirectory - - Add the plugin element `` to `res/xml/config.xml` - -Sample change to `res/xml/config.xml` for Cordova/PhoneGap 2.x: - -```diff ---- config.xml.orig 2015-04-14 14:03:05.000000000 +0200 -+++ res/xml/config.xml 2015-04-14 14:08:08.000000000 +0200 -@@ -36,6 +36,7 @@ - - - -+ - - - -``` - -Before building for the first time, you have to update the project with the desired version of the Android SDK with a command like: - - android update project --path $(pwd) --target android-19 - -(assuming Android SDK 19, use the correct desired Android SDK number here) - -**NOTE:** using this plugin on Cordova pre-3.0 requires the following changes to `SQLitePlugin.java`: - -```diff -diff -u Cordova-sqlite-storage/src/android/io/liteglue/SQLitePlugin.java src/io/liteglue/SQLitePlugin.java ---- Cordova-sqlite-storage/src/android/io/liteglue/SQLitePlugin.java 2015-04-14 14:05:01.000000000 +0200 -+++ src/io/liteglue/SQLitePlugin.java 2015-04-14 14:10:44.000000000 +0200 -@@ -22,8 +22,8 @@ - import java.util.regex.Matcher; - import java.util.regex.Pattern; - --import org.apache.cordova.CallbackContext; --import org.apache.cordova.CordovaPlugin; -+import org.apache.cordova.api.CallbackContext; -+import org.apache.cordova.api.CordovaPlugin; - - import org.json.JSONArray; - import org.json.JSONException; -``` - -## Manual installation - iOS version - -### SQLite library - -In the Project "Build Phases" tab, select the _first_ "Link Binary with Libraries" dropdown menu and add the library `libsqlite3.dylib` or `libsqlite3.0.dylib`. - -**NOTE:** In the "Build Phases" there can be multiple "Link Binary with Libraries" dropdown menus. Please select the first one otherwise it will not work. - -### SQLite Plugin - -- Copy `SQLitePlugin.[hm]` from `src/ios` into your project Plugins folder and add them in XCode (I always just have "Create references" as the option selected). -- Copy `SQLitePlugin.js` from `www` into your project `www` folder -- Enable the SQLitePlugin in `config.xml` - -Sample change to `config.xml` for Cordova/PhoneGap 2.x: - -```diff ---- config.xml.old 2013-05-17 13:18:39.000000000 +0200 -+++ config.xml 2013-05-17 13:18:49.000000000 +0200 -@@ -39,6 +39,7 @@ - - - -+ - - - -``` - ## Installation test ### Easy installation test @@ -710,70 +612,78 @@ Assuming your app has a recent template as used by the Cordova create script, ad }); ``` -### Old installation test - -Make a change like this to index.html (or use the sample code) verify proper installation: - -```diff ---- index.html.old 2012-08-04 14:40:07.000000000 +0200 -+++ assets/www/index.html 2012-08-04 14:36:05.000000000 +0200 -@@ -24,7 +24,35 @@ - PhoneGap - - -- -+ -+ -+ -+ - - - -``` - # Support -## Reporting issues +## Policy -If you have an issue with the plugin please check the following first: +Free support is provided on a best-effort basis and is only available in public forums. Please follow the steps below to be sure you have done your best before requesting help. + +Commercial support is available by contacting: + +## Before asking for help + +First steps: +- Verify that you have followed the steps in [brodybits / Cordova-quick-start-checklist](https://github.com/brodybits/Cordova-quick-start-checklist) +- Try the new echo test as described above +- Check the troubleshooting steps and pitfalls in [brodybits / Cordova-troubleshooting-guide](https://github.com/brodybits/Cordova-troubleshooting-guide) + +and check the following: - You are using the latest version of the Plugin Javascript & platform-specific Java or Objective-C source from this repository. - You have installed the Javascript & platform-specific Java or Objective-C correctly. - You have included the correct version of the cordova Javascript and SQLitePlugin.js and got the path right. - You have registered the plugin properly in `config.xml`. -If you still cannot get something to work, please create a fresh, clean Cordova project, add this plugin according to the instructions above, and try a simple test program. +If you still cannot get something to work: +- create a fresh, clean Cordova project; +- add this plugin according to the instructions above; +- double-check that you follwed the steps in [brodybits / Cordova-quick-start-checklist](https://github.com/brodybits/Cordova-quick-start-checklist); +- try a simple test program; +- double-check the troubleshooting steps and pitfalls in [brodybits / Cordova-troubleshooting-guide](https://github.com/brodybits/Cordova-troubleshooting-guide) -If you continue to see the issue in a new, clean Cordova project: +If you continue to see the issue in the fresh, clean Cordova project: - Make the simplest test program you can to demonstrate the issue, including the following characteristics: - it completely self-contained, i.e. it is using no extra libraries beyond cordova & SQLitePlugin.js; - if the issue is with *adding* data to a table, that the test program includes the statements you used to open the database and create the table; - if the issue is with *retrieving* data from a table, that the test program includes the statements you used to open the database, create the table, and enter the data you are trying to retrieve. +## What will be supported for free + +Please make a small, self-contained test program that can demonstrate your problem and post it. Please do not use any other plugins or frameworks than are absolutely necessary to demonstrate your problem. + +In case of a problem with a pre-populated database, please post your entire project. + +## Support for issues with Angular/"ngCordova"/Ionic + +Free support for issues with Angular/"ngCordova"/Ionic will only be provided if you can demonstrate that you can do the same thing without such a framework. +- Make a fresh, clean ngCordova or Ionic project with a test program that demonstrates the issue and post it. Please do not use any other plugins or frameworks unless absolutely necessary to demonstrate your issue. +- Make another project without any form of Angular including ngCordova or Ionic, with the same test program to show that it will work outside Angular/"ngCordova"/Ionic. + +## What information is needed for help + +Please include the following: +- Which platform(s) Android/iOS/WP8/Windows 8.1/Windows Phone 8.1 +- 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. + +## Please do NOT use any of these formats + +- screen casts or videos +- RAR or similar archive formats +- Intel, MS IDE, or similar project formats unless absolutely necessary + +## Where to ask for help + +Once you have followed the directions above, you may request free support in the following location(s): +- [litehelpers / Cordova-sqlite-storage / issues](https://github.com/litehelpers/Cordova-sqlite-storage/issues) +- TBD ???: ~~[litehelpers / Cordova-sqlite-help](https://github.com/litehelpers/Cordova-sqlite-help)~~ + +Please include the information described above otherwise. + +## Professional support + +Professional support is available, please contact: + # Unit tests Unit testing is done in `spec`. @@ -854,14 +764,8 @@ The adapter is now part of [PouchDB](http://pouchdb.com/) thanks to [@nolanlawso - Always use `git mv` to move files & directories; - Never mix a move/rename operation with any other changes in the same commit. -## Major version branches - -TBD FIX: +## Contact -- `common-src` - source for Android, iOS, and Windows (8.1) versions (shared with [litehelpers / Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter)) -- `new-common-rc` - pre-release version for Android/iOS/Windows (8.1), including library dependencies for Android and Windows (8.1) -- `wp-src` - source for Android (*not* using [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector)), iOS, WP(7/8), ~~and Amazon Fire-OS~~ versions -- `wp-master-rc` - pre-release version for Android(*not* using [Android-sqlite-connector](https://github.com/liteglue/Android-sqlite-connector))/iOS/WP(7/8), including source for CSharp-SQLite (C#) library classes -- `master-rc` - pre-release version for all supported platforms, including library dependencies for Android, Windows (8.1), and WP(7/8) -- [FUTURE TBD] ~~`master` - version for release, to be included in PhoneGap build.~~ + +LinkedIn: https://www.linkedin.com/in/chrisbrody diff --git a/package.json b/package.json index 9a5952621..4730a0723 100644 --- a/package.json +++ b/package.json @@ -1,27 +1,23 @@ { - "name": "cordova-sqlite-common", - "version": "0.7.2-common-dev", - "description": "Native interface to SQLite for PhoneGap/Cordova (common version-limited functionality)", + "name": "cordova-sqlite-storage", + "version": "0.8.0-pre", + "description": "Native interface to SQLite for PhoneGap/Cordova (core version)", "cordova": { - "id": "cordova-sqlite-common", + "id": "cordova-sqlite-storage", "platforms": [ "android", - "ios", - "windows", - "amazon-fireos" + "ios" ] }, "repository": { "type": "git", - "url": "https://github.com/litehelpers/cordova-sqlite-common.git" + "url": "https://github.com/litehelpers/Cordova-sqlite-storage.git" }, "keywords": [ "sqlite", "ecosystem:cordova", "cordova-android", - "cordova-ios", - "cordova-windows", - "cordova-amazon-fireos" + "cordova-ios" ], "engines": [ { @@ -32,7 +28,7 @@ "author": "various", "license": "MIT", "bugs": { - "url": "https://github.com/litehelpers/cordova-sqlite-common/issues" + "url": "https://github.com/litehelpers/Cordova-sqlite-storage/issues" }, - "homepage": "https://github.com/litehelpers/cordova-sqlite-common" + "homepage": "https://github.com/litehelpers/Cordova-sqlite-storage" } diff --git a/plugin.xml b/plugin.xml index 40ba9fc65..964636010 100644 --- a/plugin.xml +++ b/plugin.xml @@ -1,17 +1,17 @@ + id="cordova-sqlite-storage" + version="0.8.0-pre"> - Cordova sqlite storage (common) + Cordova sqlite storage plugin (core version) MIT sqlite Native interface to SQLite for PhoneGap/Cordova. Allows you to use more storage and provides more flexibility than the standard Web SQL database (window.openDatabase). - Various + Litehelpers/Various