List of "one-way migrations" that define the current DB schema.
List of "one-way migrations" that define the current DB schema... See the Database overview.
Returns a ContentQuery referring to all rows in one of the tables of this database, which may be used directly, or used to seed a RecordManager for the ORM.
Returns a ContentQuery referring to all rows in one of the tables of this database, which may be used directly, or used to seed a RecordManager for the ORM.
Throws an assertion error if called from anywhere but this activity's thread.
Throws an assertion error if called from anywhere but this activity's thread.
Close the facility.
Close the facility.
First, decrements the "nested open" count. If it has reached
zero, do a "real" close, using the protected realclose method.
Otherwise, some other activity is still using the facility, and
it stays open.
When the last activity or service calls close, the facility
actually does shut down, using the protected realClose method,
which will shut down threads, close files, or whatever.
Tag for the facility to use in log entries
Tag for the facility to use in log entries
Get a readable Android SQLiteDatabase object, for direct invocation
of core APIs.
Get a readable Android SQLiteDatabase object, for direct invocation
of core APIs.
Get a writable Android SQLiteDatabase object, for direct invocation
of core APIs.
Get a writable Android SQLiteDatabase object, for direct invocation
of core APIs.
Writes a debugging log method, using the facility's logTag
Writes a debugging log method, using the facility's logTag
Invoked when the database is created.
Invoked when the database is created. Default behavior is to
run through the complete list of schemaUpdates.
Invoked when the database is created.
Invoked when the database is created. Default behavior is to
run through the sublist of schemaUpdates from the prior version
to the end (which defines the current version).
Open the facility.
Open the facility.
If the facility isn't already open, does setup which depends on
the particular facility (which may involve opening files,
starting threads, or whatever) --- a "real" open, using the
protected realOpen method. The given Context may be used
for setup, depending on the nature of the facility.
If it is already open, just increments a "nested open" count;
see close below.
Run func on the facility's thread.
Run func on the facility's thread.
Schema version.
Schema version. By default, the length of the schemaUpdates list.
Class for database singletons. Manages setup and schema upgrades, and makes the tables database available as Positronic Net ContentRepositorys which can be queried directly, or manipulated via the orm.
Or, if you just want the schema maintenance support, you can call
getReadableDatabaseandgetWritableDatabase, and use the standard platform APIs for everything else.Most behavior is inherited from ThreadlessDatabase. (In fact, this is just ThreadlessDatabase with WorkerThread mixed in. On Android, it's usually best practice to run database work in the background, so by default, the machinery to facilitate that is there; if you really want a ThreadlessDatabase, you can get one, but you do have to ask.)
Schema definition and management
Note that
opening a Database does not trigger any I/O; that action is delayed until the first query (at which point we also perform any schema updates, etc.). It is strongly recommended that this not be done on anActivitymain UI thread.Schema definitions are ordinarily done by supplying a list of table definitions,
ALTER TABLEupgrades, etc., as the value ofschemaUpdates. The idea is that each of these statements defines a database upgrade. The way this relates to the standardSQLiteOpenHelpermachinery is as follows:versionis the number of statements on the listonCreateruns them allonUpdateruns all after the old version, to get to the current versionThe upshot is that you can add statements to the list; the current schema is defined by what you get from evaluating them all, and updates will run the missing ones on the fly.
(This arrangement is effectively a very cut-down version of the migrations system in the Ruby on Rails ActiveRecord ORM, which also features database versions defined implicitly by a stream of updates. However, there's no support here for schema downgrades, nor for transparently handling updates coming from multiple development streams.)
Using the database
There are two ways to use a database, once you've opened it.
The first is simply to call
getWritableDatabaseandgetReadableDatabase, which gets you a straightSQLiteDatabaseobject, with the full standard API.The second is that if you have a database named, say,
TodoDb, with a table namedtodo_itemsthenTodoDb("todo_items")returns a ContentQuery which may be used to manipulate all rows in the table directly, or through a RecordManager.