You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
200 lines
5.9 KiB
Plaintext
200 lines
5.9 KiB
Plaintext
# Database abstraction layer
|
|
|
|
Nexus uses a custom abstraction layer for SQLite database operations. It
|
|
has a NoSQL-like API, meaning that objects work like dicts or lists
|
|
where possible and appropriate.
|
|
|
|
The abstraction layer can be used by importing `nexus.core.db`.
|
|
|
|
! All tables that this abstraction layer is used for, **must** have a
|
|
`ROWID` alias named `id`.
|
|
|
|
{TOC}
|
|
|
|
^ Database([**filename**])
|
|
|
|
Creates a new Database connection representing an SQLite
|
|
database with the given filename. If it does not exist, it is
|
|
created.
|
|
|
|
filename::
|
|
**Optional.** Filename of the SQLite database.
|
|
|
|
^ Database.setup()
|
|
|
|
Attempts to set up the tables needed for Nexus in the database.
|
|
If the tables already exist, nothing happens.
|
|
|
|
^ Database.query(**query**[, params=**params**])
|
|
|
|
Runs a custom query against the database, and returns an
|
|
sqlite3.cursor object, that you can use to retrieve the results
|
|
from (using .fetchone(), .fetchmany(**size**), or .fetchall()).
|
|
The cursor will return Row objects, like other functions in the
|
|
abstraction layer do.
|
|
|
|
You'll only need this if you need to run queries that aren't
|
|
covered by any of the other functions; the functions specified
|
|
in the abstraction layer are prefered for performance reasons.
|
|
|
|
^ Database[**table_name**]
|
|
Database.get_database_table(**table_name**)
|
|
|
|
Retrieves a DatabaseTable object representing the table in the
|
|
database with the specified table name. Table objects are reused
|
|
where appropriate, to minimize resource usage and state issues.
|
|
|
|
While a DatabaseTable does not immediately load all data from
|
|
the table like a MemoryTable does, it **does** retain an
|
|
internal cache of retrieved rows. You will want to .purge() this
|
|
cache regularly if you use the table a lot.
|
|
|
|
! The existence of a table is not checked. You need to make sure
|
|
that the table exists by yourself, if you cannot rely on this!
|
|
|
|
table_name::
|
|
The name of the table you wish to work with.
|
|
|
|
@ Accessing a database table
|
|
|
|
$ db = Database("test.db")
|
|
table = db["sample_table"]
|
|
|
|
@ Accessing a database table through the explicit function
|
|
|
|
$ db = Database("test.db")
|
|
table = db.get_database_table("sample_table")
|
|
|
|
^ Database.get_memory_table(**table_name**)
|
|
|
|
Retrieves a MemoryTable object representing the specified table.
|
|
A MemoryTable, upon creation, will immediately load all data
|
|
from the database table it represents, and keep it in memory. It
|
|
is reused where possible, just like a DatabaseTable.
|
|
|
|
A MemoryTable is intended to be used for cases where frequent
|
|
lookup of data in small tables is necessary, eliminating the
|
|
SQLite lookup overhead.
|
|
|
|
! The existence of a table is not checked. You need to make sure
|
|
that the table exists by yourself, if you cannot rely on this!
|
|
|
|
! If your database table is modified by another application or
|
|
instance, the data in your MemoryTable will be out of sync.
|
|
In this case, use a regular MemoryTable or .refresh() the data
|
|
frequently.
|
|
|
|
table_name::
|
|
The name of the table you wish to work with.
|
|
|
|
@ Accessing a database table and keeping it in memory
|
|
|
|
$ db = Database("test.db")
|
|
table = db.get_memory_table("sample_table")
|
|
|
|
^ DatabaseTable[**row_id**]
|
|
MemoryTable[**row_id**]
|
|
|
|
Retrieves a Row object representing the row in the table with
|
|
the specified identifier (in the `id` field). Data is retrieved
|
|
immediately.
|
|
|
|
row_id::
|
|
The identifier of the row to retrieve.
|
|
|
|
### Exceptions
|
|
|
|
KeyError::
|
|
Raised when a row with the given identifier does not
|
|
exist in the table.
|
|
|
|
^ DatabaseTable[**row_id**] = **row**
|
|
MemoryTable[**row_id**] = **row**
|
|
|
|
Inserts a new row into the database. This can **not** be used to
|
|
edit an existing row; to do so, edit the Row object for that row
|
|
directly.
|
|
|
|
If you do not want to explicitly specify a row identifier, use
|
|
the .append() method instead.
|
|
|
|
row_id::
|
|
The identifier to give the row in the database.
|
|
|
|
row::
|
|
A Row object representing the new row to insert.
|
|
|
|
### Exceptions
|
|
|
|
TypeError::
|
|
Raised when a row with the given identifier already
|
|
exists.
|
|
|
|
^ DatabaseTable.append(**row**)
|
|
MemoryTable.append(**row**)
|
|
|
|
Inserts a new row into the table, and lets SQLite assign it an
|
|
identifier. This is the method you'll usually want to use.
|
|
|
|
row::
|
|
A Row object representing the new row to insert.
|
|
|
|
^ Row()
|
|
|
|
Creates a new Row object. You'll only need to use this if you
|
|
want to insert a new row into a table.
|
|
|
|
You do not need to immediately specify a table name or row data.
|
|
Instead, you can just set column values on the Row object after
|
|
creating it, and tell it what table to be inserted to by using
|
|
any of the insertion methods on a DatabaseTable or MemoryTable.
|
|
|
|
^ Row[**column_name**]
|
|
|
|
Returns the value of the specified column in the row.
|
|
|
|
column_name::
|
|
The column whose value you wish to retrieve.
|
|
|
|
### Exceptions
|
|
|
|
KeyError::
|
|
Returned when there is no such column in the table that
|
|
the row belongs to.
|
|
|
|
^ Row[**column_name**] = **value**
|
|
|
|
Sets (or changes) the data for the given column in the row.
|
|
|
|
! The change is not immediately reflected in the database (or
|
|
memory table). To apply your changes, you need to .commit().
|
|
|
|
! This does not check whether such a column exists! If you
|
|
specify an invalid column name, the data will simply never be
|
|
inserted.
|
|
|
|
column_name::
|
|
The column whose value you wish to set or change.
|
|
|
|
value::
|
|
The value to set the column to.
|
|
|
|
^ Row.commit()
|
|
|
|
Process all changes you have made to the column data for the
|
|
row. This will run one or more SQL queries.
|
|
|
|
You don't need to do this when inserting a new row; the
|
|
insertion methods for the table will do this for you
|
|
automatically.
|
|
|
|
^ Row.rollback()
|
|
|
|
Cancels all the changes you have made to the column data for the
|
|
row, and returns it to the original state. The "original state"
|
|
will be state the row was in when you last retrieved or
|
|
committed it.
|
|
|
|
Note that this will only work with uncommitted changes; after
|
|
you commit a change, it is final and not reversible.
|