Next: , Previous: Relational Database, Up: Relational Database

6.1.1 Using Databases

(require 'databases) This enhancement wraps a utility layer on relational-database which provides:

Database Sharing

Auto-sharing refers to a call to the procedure open-database returning an already open database (procedure), rather than opening the database file a second time.

Note: Databases returned by open-database do not include wrappers applied by packages like Embedded Commands. But wrapped databases do work as arguments to these functions.

When a database is created, it is mutable by the creator and not auto-sharable. A database opened mutably is also not auto-sharable. But any number of readers can (open) share a non-mutable database file.

This next set of procedures mirror the whole-database methods in Database Operations. Except for create-database, each procedure will accept either a filename or database procedure for its first argument.

— Function: create-database filename base-table-type

filename should be a string naming a file; or #f. base-table-type must be a symbol naming a feature which can be passed to require. create-database returns a new, open relational database (with base-table type base-table-type) associated with filename, or a new ephemeral database if filename is #f.

create-database is the only run-time use of require in SLIB which crosses module boundaries. When base-table-type is required by create-database; it adds an association of base-table-type with its relational-system procedure to mdbm:*databases*.

alist-table is the default base-table type: 

          (require 'databases)
          (define my-rdb (create-database "my.db" 'alist-table))

Only alist-table and base-table modules which have been required will dispatch correctly from the open-database procedures. Therefore, either pass two arguments to open-database, or require the base-table of your database file uses before calling open-database with one argument.

— Procedure: open-database! rdb base-table-type

Returns mutable open relational database or #f.

— Function: open-database rdb base-table-type

Returns an open relational database associated with rdb. The database will be opened with base-table type base-table-type). — Function: open-database rdb

Returns an open relational database associated with rdb. open-database will attempt to deduce the correct base-table-type.

— Function: write-database rdb filename

Writes the mutable relational-database rdb to filename.

— Function: sync-database rdb

Writes the mutable relational-database rdb to the filename it was opened with.

— Function: solidify-database rdb

Syncs rdb and makes it immutable.

— Function: close-database rdb

rdb will only be closed when the count of open-database - close-database calls for rdb (and its filename) is 0. close-database returns #t if successful; and #f otherwise.

— Function: mdbm:report

Prints a table of open database files. The columns are the base-table type, number of opens, ‘!’ for mutable, the filename, and the lock certificate (if locked). 

     (mdbm:report)
     -|
       alist-table 003   /usr/local/lib/slib/clrnamdb.scm
       alist-table 001 ! sdram.db jaffer@aubrey.jaffer.3166:1038628199
Opening Tables
— Function: open-table rdb table-name

rdb must be a relational database and table-name a symbol.

open-table returns a "methods" procedure for an existing relational table in rdb if it exists and can be opened for reading, otherwise returns #f.

— Procedure: open-table! rdb table-name

rdb must be a relational database and table-name a symbol.

open-table! returns a "methods" procedure for an existing relational table in rdb if it exists and can be opened in mutable mode, otherwise returns #f.

Defining Tables
— Function: define-domains rdb row5 ...

Adds the domain rows row5 ... to the ‘*domains-data*’ table in rdb. The format of the row is given in Catalog Representation. 

          (define-domains rdb '(permittivity #f complex? c64 #f))
— Function: add-domain rdb row5

Use define-domains instead.

— Function: define-tables rdb spec-0 ...

Adds tables as specified in spec-0 ... to the open relational-database rdb. Each spec has the form: 

          (<name> <descriptor-name> <descriptor-name> <rows>)

or 

          (<name> <primary-key-fields> <other-fields> <rows>)

where <name> is the table name, <descriptor-name> is the symbol name of a descriptor table, <primary-key-fields> and <other-fields> describe the primary keys and other fields respectively, and <rows> is a list of data rows to be added to the table.

<primary-key-fields> and <other-fields> are lists of field descriptors of the form: 

          (<column-name> <domain>)

or 

          (<column-name> <domain> <column-integrity-rule>)

where <column-name> is the column name, <domain> is the domain of the column, and <column-integrity-rule> is an expression whose value is a procedure of one argument (which returns #f to signal an error).

If <domain> is not a defined domain name and it matches the name of this table or an already defined (in one of spec-0 ...) single key field table, a foreign-key domain will be created for it.

Listing Tables
— Function: list-table-definition rdb table-name

If symbol table-name exists in the open relational-database rdb, then returns a list of the table-name, its primary key names and domains, its other key names and domains, and the table's records (as lists). Otherwise, returns #f.

The list returned by list-table-definition, when passed as an argument to define-tables, will recreate the table.