On this page:
gen-data-class
table-name-normalizer
column-name-normalizer
join-name-normalizer
table-name-externalizer
set-odbc-dbsystem-type!

2 Automated Data Class Generation

A powerful feature of Racquel is the ability to generate data-class mappings automatically using database schema metadata. This allows for data classes to be defined for all the tables in a database without the tedious effort of manually coding the mappings.

syntax

(gen-data-class db-connection
                table-name
                #:db-system-type db-system-type-kw
                #:generate-joins? generate-joins-kw
                #:generate-reverse-joins? generate-reverse-joins-kw
                #:schema-name schema-name
                #:inherits base-class
                #:table-name-normalizer proc
                #:column-name-normalizer proc
                #:join-name-normalizer proc
                #:table-name-externalizer proc
                #:print? print-kw
                #:prepare? prepare-kw
                data-class-clause ...)
 
db-system-type-kw = 
  | #:db-system-type db-system-type
     
generate-joins-kw = 
  | #:generate-joins? (or/c #t #f)
     
generate-reverse-joins-kw = 
  | #:generate-reverse-joins? (or/c #t #f)
     
schema-name-kw = 
  | #:schema-name (string?)
     
inherits-kw = 
  | #:inherits (string?)
     
table-name-normalizer-kw = 
  | #:table-name-normalizer
     
column-name-normalizer-kw = 
  | #:column-name-normalizer
     
join-name-normalizer-kw = 
  | #:join-name-normalizer
     
table-name-externalizer-kw = 
  | #:table-name-externalizer
     
print-kw = 
  | #:print? (or/c #t #f)
Generates a data class from the specified table-name using the db-connection. If the database system type is an ODBC connection, then the particular system type can be specified using the #:db-system-type keyword. (This is not necessary if the database system type has already been defined by calling set-odbc-dbsystem-type!. If the #:db-system-type is not specified, then the database system type is determined from the dbsystem-name of the db-connection, where the 'odbc database system is assumed to be SQL Server.

The generate-joins? and generate-reverse-joins keywords control the automatic generation of joins and reverse joins. Joins are determined based on foreign key constraints in the database, and reverse joins are based on any foreign key contraints referencing it. By default, joins are generated, but reverse joins are not.

In some cases, the table name may not be unique in the database server’s metadata. In those cases, the schema-name can be used to specify the schema that the table resides in.

The base class of the generated data class can be specified using the #:inherits keyword. The default base-class is object%.

Behavior of the map generation can be controlled by customizing the normalizer procedures which normalize database names into Racket symbols. Generation of external names from the symbol can also be controlled using the externalizer procedures. A normalizer or externalizer can be customized by specifying the procedure to use with the appropriate keyword. An example of a situation where one would want to override the default normalizers is if table names in a database started with a prefix.

Below are the default normalizers and externalizers.

procedure

(table-name-normalizer table-name)  (string?)

  table-name : string?
This normalizer converts database table names into Racket class names, using a set of rules. First, the normalizer will convert mixed-case names, e.g. "MixedCase", and make the all lower-case with hyphens between the names, e.g. "mixed-case". It will then convert any underscores to hyphens. Finally, it will append a percent sign to the end of the name, since that is the Racket standard for naming classes.

> (table-name-normalizer "ExampleTable_Name")
  example-table-name%

This is default normalizer for table names if the #:table-name-externalizer keyword is not specified.

procedure

(column-name-normalizer table-name)  (string?)

  table-name : string?
This converts column names of a table into Racket symbols, following a set of rules. The rules are similar to those for the table-name-normalizer. First mixed-case names are converted to lower-case with hyphens, then underscores are converted to hyphens.

> (column-name-normalizer "ExampleColumn_Name")
  example-column-name

This is default normalizer for table names if the #:column-name-externalizer keyword is not specified.

procedure

(join-name-normalizer table-name)  (string?)

  table-name : string?
This converts joined table names into Racket symbols, following a set of rules. The rules are similar to those for the column-name-normalizer. First mixed-case names are converted to lower-case with hyphens, then underscores are converted to hyphens. Also, if the cardinality of the join is 'one-to-many, an "s" is appended to the end of the name (or "es" if the name ends with an "s".)

> (join-name-normalizer "JoinExample_Address")
  join-example-addresses

This is default normalizer for table names if the #:join-name-externalizer keyword is not specified.

procedure

(table-name-externalizer table-name)  (string?)

  table-name : string?
Converts a database table name to an external name for JSON or XML serialization. The default is no change at all to the table name.

procedure

(set-odbc-dbsystem-type! odbc-sys-type)  (void?)

  odbc-sys-type : (or/c 'sqlserver 'oracle 'db2)
If the database system being used is either Oracle or DB/2, then the database system type needs to be set to distinguish the ODBC connection from a SQL Server connection, which is assumed for an ODBC connection is it is not specified using this procedure.