<divclass="children"><h1>Database abstraction layer</h1><divclass="text">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.</div><divclass="text">The abstraction layer can be used by importing <spanclass="fixed">nexus.core.db</span>.</div><divclass="exclamation"><strong>Important:</strong> All tables that this abstraction layer is used for, <em>must</em> have a <spanclass="fixed">ROWID</span> alias named <spanclass="fixed">id</span>. <divclass="children"></div></div><divclass="toc"><h2>Table of contents</h2><ul><li><ahref="#Databasefilename">Database([filename])</a> Creates a new Database connection representing an SQLite database with the given... </li><li><ahref="#Database_setup">Database.setup()</a> Attempts to set up the tables needed for Nexus in the database. If the tables... </li><li><ahref="#Database_queryqueryparamsparams">Database.query(query[, params=params])</a> Runs a custom query against the database, and returns an sqlite3.cursor object,... </li><li><ahref="#Databasetable_name">Database[table_name]</a> Retrieves a DatabaseTable object representing the table in the database with the... <spanclass="alternatives">(also: Database.get_database_table(table_name))</span></li><li><ahref="#Database_get_memory_tabletable_name">Database.get_memory_table(table_name)</a> Retrieves a MemoryTable object representing the specified table. A MemoryTable,... </li><li><ahref="#DatabaseTablerow_id">DatabaseTable[row_id]</a> Retrieves a Row object representing the row in the table with the specified... <spanclass="alternatives">(also: MemoryTable[row_id])</span></li><li><ahref="#DatabaseTablerow_idrow">DatabaseTable[row_id] = row</a> Inserts a new row into the database. This can <em>not</em> be used to edit an... <spanclass="alternatives">(also: MemoryTable[row_id] = row)</span></li><li><ahref="#DatabaseTable_appendrow">DatabaseTable.append(row)</a> Inserts a new row into the table, and lets SQLite assign it an identifier. This... <spanclass="alternatives">(also: MemoryTable.append(row))</span></li><li><ahref="#DatabaseTable_purge">DatabaseTable.purge()</a> Purges the internal row cache of a DatabaseTable. </li><li><ahref="#MemoryTable_refresh">MemoryTable.refresh()</a> Replaces the current copy of the table in memory, with a newly retrieved copy.... </li><li><ahref="#Row">Row()</a> Creates a new Row object. You'll only need to use this if you want to insert a... </li><li><ahref="#Rowcolumn_name">Row[column_name]</a> Returns the value of the specified column in the row. </li><li><ahref="#Rowcolumn_namevalue">Row[column_name] = value</a> Sets (or changes) the data for the given column in the row. </li><li><ahref="#Row_commit">Row.commit()</a> Process all changes you have made to the column data for the row. This will run... </li><li><ahref="#Row_rollback">Row.rollback()</a> Cancels all the changes you have made to the column data for the row, and... </li></ul></div><divclass="definition"><aname="Databasefilename">Database([<em>filename</em>]) <divclass="children"><divclass="text">Creates a new Database connection representing an SQLite database with the given filename. If it does not exist, it is created.</div><dl><dt>filename</dt><dd><em>Optional.</em> Filename of the SQLite database.<divclass="children"></div></dd></dl></div></a></div><divclass="definition"><aname="Database_setup">Database.setup() <divclass="children"><divclass="text">Attempts to set up the tables needed for Nexus in the database. If the tables already exist, nothing happens.</div></div></a></div><divclass="definition"><aname="Database_queryqueryparamsparams">Database.query(<em>query</em>[, params=<em>params</em>]) <divclass="children"><divclass="text">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(<em>size</em>), or .fetchall()). The cursor will return Row objects, like other functions
table = db["sample_table"]</pre></div></div><divclass="example">Example: Accessing a database table through the explicit function <divclass="children"><h7>Code:</h7><preclass="code">db = Database("test.db")
table = db.get_database_table("sample_table")</pre></div></div></div></a></div><divclass="definition"><aname="Database_get_memory_tabletable_name">Database.get_memory_table(<em>table_name</em>) <divclass="children"><divclass="text">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.</div><divclass="text">A MemoryTable is intended to be used for cases where frequent lookup of data in small tables is necessary, eliminating the SQLite lookup overhead.</div><divclass="exclamation"><strong>Important:</strong> 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! <divclass="children"></div></div><divclass="exclamation"><strong>Important:</strong> 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. <divclass="children"></div></div><dl><dt>table_name</dt><dd>The name of the table you wish to work with.<divclass="children"></div></dd></dl><divclass="example">Example: Accessing a database table and keeping it in memory <divclass="children"><h7>Code:</h7><preclass="code">db = Database("test.db")
table = db.get_memory_table("sample_table")</pre></div></div></div></a></div><divclass="definition"><aname="DatabaseTablerow_id">DatabaseTable[<em>row_id</em>]<br>MemoryTable[<em>row_id</em>] <divclass="children"><divclass="text">Retrieves a Row object representing the row in the table with the specified identifier (in the <spanclass="fixed">id</span> field). Data is retrieved immediately.</div><dl><dt>row_id</dt><dd>The identifier of the row to retrieve.<divclass="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>KeyError</dt><dd>Raised when a row with the given identifier does not exist in the table.<divclass="children"></div></dd></dl></div></a></div><divclass="definition"><aname="DatabaseTablerow_idrow">DatabaseTable[<em>row_id</em>] = <em>row</em><br>MemoryTable[<em>row_id</em>] = <em>row</em><divclass="children"><divclass="text">Inserts a new row into the database. This can <em>not</em> be used to edit an existing row; to do so, edit the Row object for that row directly.</div><divclass="text">If you do not want to explicitly specify a row identifier, use the .append() method instead.</div><dl><dt>row_id</dt><dd>The identifier to give the row in the database.<divclass="children"></div></dd></dl><dl><dt>row</dt><dd>A Row object representing the new row to insert.<divclass="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>TypeError</dt><dd>Raised when a row with the given identifier already exists.<divclass="children"></div></dd></dl></div></a></div><divclass="definition"><aname="DatabaseTable_appendrow">DatabaseTable.append(<em>row</em>)<br>MemoryTable.append(<em>row</em>) <divclass="children"><divclass="text">Inserts a new row into the table, and lets SQLite assign it an identifier. This is the method you'll usually want to use.</div><dl><dt>row</dt><dd>A Row object representing the new row to insert.<divclass="children"></div></dd></dl></div></a></div><divclass="definition"><aname="DatabaseTable_purge">DatabaseTable.purge() <divclass="children"><divclass="text">Purges the internal row cache of a DatabaseTable.</div><divclass="exclamation"><strong>Important:</strong> You cannot use this method for a MemoryTable! Use .refresh() instead. <divclass="children"></div></div></div></a></div><divclass="definition"><aname="MemoryTable_refresh">MemoryTable.refresh() <divclass="children"><divclass="text">Replaces the current copy of the table in memory, with a newly retrieved copy. You'll need to call this regularly when you have multiple applications modifying the same table, to prevent going out of sync. If synchronized data is absolutely essential at all times, use a DatabaseTable instead.</div><divclass="exclamation"><strong>Important:</strong> You cannot use this method for a DatabaseTable! Use .purge() instead. <divclass="children"></div></div></div></a></div><divclass="definition"><aname="Row">Row() <divclass="children"><divclass="text">Creates a new Row object. You'll only need to use this if you want to insert a new row into a table.</div><divclass="text">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.</div></div></a></div><divclass="definition"><aname="Rowcolumn_name">Row[<em>column_name</em>] <divclass="children"><divclass="text">Returns the value of the specified column in the row.</div><dl><dt>column_name</dt><dd>The column whose value you wish to retrieve.<divclass="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>KeyError</dt><dd>Returned when there is no such column in the table that the row belongs to.<divclass="children"></div></dd></dl></div></a></div><divclass="definition"><aname="Rowcolumn_namevalue">Row[<em>column_name</em>] = <em>value</em><divclass="children"><divclass="text">Sets (or changes) the data for the given column in the row.</div><divclass="exclamation"><strong>Important:</strong> The change is not immediately reflected in t