6.1.1 Using Databases

(require 'databases)

This enhancement wraps a utility layer on relational-database which provides:

• Identification of open databases by filename.
• Automatic sharing of open (immutable) databases.
• Automatic loading of base-table package when creating a database.
• Detection and automatic loading of the appropriate base-table package when opening a database.
• Table and data definition from Scheme lists.

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.