1.5.9.1 The Database Object

The Database object is used primarily as a container for Table objects. The function reference is shown below:

class Database( [,name=None])

name is an arbitrary name for the database used by the str() and repr() funcitons. If not specified name is set to the class name for the database.

addTable( table): Adds the table object table to the database

init( cursor): Initialise the database by associating it with the web.database cursor specified bt cursor. Once the database is initialised you can't add or change the table definitions.

createTables( ): Create all the necessary tables

dropTables( [ignoreErrors=False]): Remove all tables defined in the database. If ignoreErrors is True don't raise an Exception if the table doesn't already exist.

tablesExist( ): Return True if all the tables exist, False otherwise.

table( name): Return the table object for the table named name

__getitem__( name): Return the table object for the table named name

keys( ): Return a tuple containing the names of the tables in the database

values( ): Return a tuple containing the web.database.object.Table objects for each of the tables in the database

items( ): Return a tuple containing 2-tuples of (key, value) pairs where the key is the table name and the value is the web.database.object.Table object.

dict( [tables=False], [rows=False]): Return all the tables a dictionary indexed by the table names. If tables is True then each table object in the dictionary if also made into a dictionary of key: Row pairs. If rows is True then each Row object of each table is made into a dictionary of column name : value pairs, except for single, multiple and related joins columns, since this could result in circular references.

has_key( key): Returns True if the database has a table table, False otherwise

output( [width=80]): Return a string representation of the database and tables in the form of a table. If width is 0 then no wrapping is done. Otherwise the table is wrapped to width characters. See the web.util.table() documentation for more information.

cursor: The underlying web.database cursor.

name: The name of the database specified by the name parameter of the constructor. Used by the str() and repr() funcitons.

Table objects can be obtained from a Database object by treating the Database object as a dictionary of Table objects referenced by their names.

For example, if a Database object named database has tables named Person and Address you would access the Person table with database['Person'] and the Address table with database['Address'].

>>> database['Person']
<web.database.object.Table 'Person'>

The Database object also provides a setup() method which can be used to setup fields if you want to create your own custom Database object.