Qt Quick Local Storage QML Types
This is a singleton type for reading and writing to SQLite databases.
Methods
- object openDatabaseSync(string name, string version, string description, int estimated_size, jsobject callback(db))
Detailed Description
To use the types in this module, import the module and call the relevant functions using the LocalStorage
type:
import QtQuick.LocalStorage 2.0 import QtQuick 2.0 Item { Component.onCompleted: { var db = LocalStorage.openDatabaseSync(...) } }
These databases are user-specific and QML-specific, but accessible to all QML applications. They are stored in the Databases
subdirectory of QQmlEngine::offlineStoragePath(), currently as SQLite databases.
Database connections are automatically closed during Javascript garbage collection.
The API can be used from JavaScript functions in your QML:
import QtQuick 2.0 import QtQuick.LocalStorage 2.0 Rectangle { width: 200 height: 100 Text { text: "?" anchors.horizontalCenter: parent.horizontalCenter function findGreetings() { var db = LocalStorage.openDatabaseSync("QQmlExampleDB", "1.0", "The Example QML SQL!", 1000000); db.transaction( function(tx) { // Create the database if it doesn't already exist tx.executeSql('CREATE TABLE IF NOT EXISTS Greeting(salutation TEXT, salutee TEXT)'); // Add (another) greeting row tx.executeSql('INSERT INTO Greeting VALUES(?, ?)', [ 'hello', 'world' ]); // Show all added greetings var rs = tx.executeSql('SELECT * FROM Greeting'); var r = "" for(var i = 0; i < rs.rows.length; i++) { r += rs.rows.item(i).salutation + ", " + rs.rows.item(i).salutee + "\n" } text = r } ) } Component.onCompleted: findGreetings() } }
The API conforms to the Synchronous API of the HTML5 Web Database API, W3C Working Draft 29 October 2009.
The SQL Local Storage example demonstrates the basics of using the Offline Storage API.
Open or create a databaseData
import QtQuick.LocalStorage 2.0 as Sql db = Sql.openDatabaseSync(identifier, version, description, estimated_size, callback(db))
The above code returns the database identified by identifier. If the database does not already exist, it is created, and the function callback is called with the database as a parameter. identifier is the name of the physical file (with or without full path) containing the database. description and estimated_size are written to the INI file (described below), but are currently unused.
May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.
When a database is first created, an INI file is also created specifying its characteristics:
Key | Value |
---|---|
Identifier | The name of the database passed to openDatabase() |
Version | The version of the database passed to openDatabase() |
Description | The description of the database passed to openDatabase() |
EstimatedSize | The estimated size (in bytes) of the database passed to openDatabase() |
Driver | Currently "QSQLITE" |
This data can be used by application tools.
db.changeVersion(from, to, callback(tx))
This method allows you to perform a Scheme Upgrade.
If the current version of db is not from, then an exception is thrown.
Otherwise, a database transaction is created and passed to callback. In this function, you can call executeSql on tx to upgrade the database.
May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.
See example below.
var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000); if (db.version == '0.1') { db.changeVersion('0.1', '0.2', function(tx) { tx.executeSql('INSERT INTO trip_log VALUES(?, ?, ?)', [ '01/10/2016','Sylling - Vikersund', '53' ]); } });
db.transaction(callback(tx))
This method creates a read/write transaction and passed to callback. In this function, you can call executeSql on tx to read and modify the database.
If the callback throws exceptions, the transaction is rolled back. Below you will find an example of a database transaction which catches exceptions.
var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000); db.transaction( try { function(tx) { tx.executeSql('INSERT INTO trip_log VALUES(?, ?, ?)', [ '01/10/2016','Sylling - Vikersund', '53' ]); } } catch (err) { console.log("Error inserting into table Greeting: " + err); } )
db.readTransaction(callback(tx))
This method creates a read-only transaction and passed to callback. In this function, you can call executeSql on tx to read the database (with SELECT statements).
results = tx.executeSql(statement, values)
This method executes a SQL statement, binding the list of values to SQL positional parameters ("?").
It returns a results object, with the following properties:
Type | Property | Value | Applicability |
---|---|---|---|
int | rows.length | The number of rows in the result | SELECT |
var | rows.item(i) | Function that returns row i of the result | SELECT |
int | rowsAffected | The number of rows affected by a modification | UPDATE, DELETE |
string | insertId | The id of the row inserted | INSERT |
May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR.
See below for an example:
// Retrieve activity date, description and distance based on minimum // distance parameter Pdistance function db_distance_select(Pdistance) { var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000); db.transaction( function(tx) { var results = tx.executeSql('SELECT rowid, date, trip_desc, distance FROM trip_log where distance >= ?',[Pdistance]'); for (var i = 0; i < results.rows.length; i++) { listModel.append({"id": results.rows.item(i).rowid, "date": results.rows.item(i).date, "trip_desc": results.rows.item(i).trip_desc, "distance": results.rows.item(i).distance}); } } }
Method Documentation
object openDatabaseSync(string name, string version, string description, int estimated_size, jsobject callback(db))
Opens or creates a local storage sql database by the given parameters.
name
is the database nameversion
is the database versiondescription
is the database display nameestimated_size
is the database's estimated size, in bytescallback
is an optional parameter, which is invoked if the database has not yet been created.
Returns the created database object.
© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.