File: usingtedia2sql.html

package info (click to toggle)
tedia2sql 1.2.12-3
links: PTS
area: main
in suites: lenny
size: 384 kB
ctags: 553
sloc: perl: 2,196; sql: 1,683; makefile: 31; sh: 24
file content (689 lines) | stat: -rw-r--r-- 30,530 bytes
parent folder | download | duplicates (2)
<html>
	<body>
		<h1>Using Dia to Interact With tedia2sql</h1>
		<hr>



		<h2>Notes on Case</h2>
		In general, you should try to use lowercase when dealing with tedia2sql and
		dealing with Dia in preparation for using tedia2sql to generate SQL DDL. Where
		you don't use lowercase, assume tedia2sql will be case-sensitive. In the
		near future, tedia2sql will support an option to convert every object, datatype,
		and keyword in your schema to UPPERCASE or lowercase.
		<p>
		In any case, tedia2sql prefers to get commands in lowercase.
		Attempts have been made to allow ALL UPPERCASE in such items as "NULL" or
		"NOT NULL" or whatever, but it is known that the code will perform best if you
		use lowercase when passing keywords to tedia2sql. In some cases, tedia2sql will
		convert your input to lowercase when dealing with it.
		<p>
		It bears repeating, soon there will be an option you can pass to tedia2sql to
		specify you want keywords, datatypes, and the like in ALL UPPERCASE, so you
		shouldn't sweat this small detail right now.

		<h2>UML and ERD</h2>
		tedia2sql can interpret a Dia UML diagram in two different
		modes. The default is to use the ERD interpretation, where
		the diamond UML 'aggregation' symbol represents the ERD
		'crows foot' symbol for the 'many' end of a one-to-many
		relationship, and the relationship direction symbol
		is used to indicate the 'owner' end of a one-to-one,
		or one-to-zero-or-one relationship. The relationship direction
		arrow points towards the 'owner' end.
		<p>
		In UML mode, using the <i>-u</i> flag, the conventional UML interpretation
		of aggregation and composition associations are used. The direction symbol
		is still used to indicate the 'owner' end of one-to-one associations
		that do not have aggregation or composition semantics.

		<h2>Creating the Dia UML Diagram</h2>
		Start up your copy of Dia. Choose the UML shape set.
		<p>
		It's important to note that you're editing a UML diagram, and not a database
		ERD. Thus, we don't call things "tables" and "columns," but instead, we call
		them "classes" and "attributes." However, since we're all DBAs here, sometimes
		we lapse into table/column terminology when it's convenient or when we forget.
		For the purpose of this document, they're synonymous. Here's a short list of
		common synonyms:
		<ul>
			<li>	class == table == relation (== view)
			<li>	attribute == column
			<li>	association == foreign-key relationship == FK constraint
			<li>	primary key == PK constraint
		</ul>
		In general, you should find the following instructions mostly intuitive. In
		fact, you might start creating Classes and Associations right away without
		reading further, pausing to read these instructions again when you're ready
		to create views, figure out how to specify datatypes, nullability, primary keys,
		indexes, permissions, etc.




		<h2>UML Classes</h2>
		Create a new class and pick its background colour. Whenever you want to create
		another class of the same style, copy this generic class and paste it to make
		the new one.
		<p>
		Edit your class. Set the name to whatever you want. Note that the generated
		SQL DDL script will use the same case as you name your class here. This doesn't
		matter on RDBMSs like Oracle and Postgres that are case-insensitive, but it
		does matter on others like Sybase that are case-sensitive.
		<p>
		If you choose the "Abstract" checkbox, this will represent a view, rather than
		a table, in the final DDL.

		<h3>Attributes for Tables</h3>
		<img src="sampleImages/ClassTable.png" align=right border=1>
		Each Attribute that you create will become a column in your table. The Attribute
		name and type will become column name/type.
		<p>
		Attribute types should be ANSI SQL 1992 (SQL'92) standard datatypes. Of course you can
		use datatypes for your target database, but this will limit portability of your
		schema. If you use SQL'92 datatypes, tedia2sql will automatically pick
		a datatype for your RDBMS if yours does not support SQL'92 datatypes. For example,
		if you use "timestamp" as a datatype and generate SQL DDL for Oracle, it will
		automatically convert this to "date".
		<p>
		The Value field can be "NULL" "NOT NULL" to generate DDL indicating this
		column is NULLable or not NULLable.
		<p>
		Value can also indicate default values: "default <i>defaultValue</i>" will specify
		that the column should default to <i>defaultValue</i>. Follow your RDBMS syntax
		here. In most RDBMSs, if the column type is a string, you must put single-quotes
		(or even, sometimes, double-quotes) around the default value, thusly: "default '<i>defaultValue</i>'".
		<p>
		You can mix the NULLability of the column and DEFAULT of the column as well. For
		example, "default <i>defaultValue</i> NOT NULL" or "default <i>defaultValue</i> NULL"
		will specify a default value of <i>defaultValue</i> and that the column is
		not NULLable and NULLable respectively.
		<p>
		If your style (like mine) calls for not capitalising NULL and NOT NULL, you can
		put them in lowercase. However, tedia2sql will not properly parse mixed-case "NULL"
		and "NOT NULL". Choose either all uppercase or all lowercase and stick with it.
		<p>
		Set Visibility to "Protected" if you want this Attribute to be
		part of the Primary Key. This will put the "pound sign" ("#")
		to the left of the Attribute on the Class object in your
		diagram, visually indicating it's part of the Primary Key. Do
		not put "NOT NULL" or any variation into your value field, as
		tedia2sql will add "NOT NULL" automatically to all attributes
		that participate in the primary key.


		<h3>Operations for Tables</h3>
		Operations are used to create either indexes or permissions (grant) statements.
		<p>
		In the case of creating indexes, you want to fill out the operation as follows:
		<ul>
			<li> Operation Name: Index name, ie: <i>idx_person_phone</i>
			<li> Operation Type: Indext type, ie: <i>index</i> or <i>unique index</i>
			<li> Parameters: Index columns -- Each parameter name is the column name
			<li> Stereotype: Index type -- For PostgreSQL, you can choose other than btree.
		</ul>
		<p>
		Example statement created:
		<pre>
			<i>create unique index INDEXNAME on CLASSNAME (param1, param2)</i>
		</pre>
		<p>
		In the case of creating permissions statments, you should fill out the operation thusly:
		<ul>
			<li> Operation Name: Permission scope, ie: <i>select</i>, <i>insert</i>, or <i>all</i>
			<li> Operation Type: Permission type, ie: <i>grant</i>
			<li> Parameters: Roles given the permission -- each parameter name is
			a role name given the permission.
		</ul>
		<p>
		Each parameter name given will create a separate permissions statement in the
		DDL file.
		<p>
		Example statements created:
		<pre>
			<i>grant select,insert,update on CLASSNAME to param1</i> <br>
			<i>grant select,insert,update on CLASSNAME to param2</i>
		</pre>
		You can ignore the Stereotype, Visibility, Class Scope, Query, and Inheritance types of
		the Operation in both Index and Permissions cases.
		<p>
		You can also ignore the Type and Default Value fields for parameters.

		<h3>Attributes for Views</h3>
		<img src="sampleImages/ClassView.png" align=right border=1>
		If you have chosen the Abstract checkbox for the Class, then this represents a
		view. Each attribute will be a column. If your view joins multiple tables, you
		should prefix each column with the table name or table alias, ie: <i>table.column</i>.
		<p>
		You do not need to fill in the type or value fields of the attributes, since
		a view doesn't have such a concept.
		<p>
		Each attribute name will be turned into a single part of the select statement
		for the view, so you can get creative here, such as:
		<pre>
			<i>tab1.name || '.' || tab2.owner as owner</i>.
		</pre>

		<h3>Operations for Views</h3>
		Each operation will become part of the from, where, order by, group by, and having
		clauses of your view. The operation name is the argument to the select section,
		and the type is the section it belongs to.
		<p>
		For instance, you might want two parts in your where clause. Thus, you'd choose
		for two different operations:
		<pre>
			name: <i>(tab1.col1 = 'hello')</i> type: <i>where</i> <br>
			name: <i>and (tab2.col1 = 7)</i> type: <i>where</i> <br>
		</pre>
		Note that you should include the 'and' or 'or' in the Operation name field for
		the second and subsequent parts of the where clause.



		<h2>UML Associations</h2>
		<img src="sampleImages/Association.png" align=right border=1>
		Make sure both sides of your association are really attached to a connection
		point on the classes, or your SQL DDL won't properly create foreign key
		statements; an error message will be printed.

		<h3>Association Name</h3>

		If omitted, tedia2sql will generate a name for the association
		foreign key constraints and and for the centre (join) table
		for many-to-many associations.

		<h4>ERD mode</h4>
		This will be the name of the foreign key created. Commonly,
		DBAs name their foreign keys to give an idea of what two tables
		are related, eg: a Person and Account tables are related
		by a foreign key constriant called <i>fk_prsn_acct</i>.
		The name of the automatically generated name in this case
		would be <i>person_fk_accountId</i>, if the name of the
		primary key is <i>id</i> (realistically, of course, we
		should expect that Person-Account would be many-to-many,
		but we ignore for now the possibility of joint accounts).

		<h4>UML mode</h4>
		In UML mode, the automatically generated name is always used
		for the name of the foreign key constriant. The relationship
		name may be used for documentation purposes.

		<h3>Role</h3>
		Each role is the name of an attribute in the class. This must
		be correct for the foreign-key statement to be syntactically
		correct. For <i>one-to</i> associations, the 'one' end of
		the association must be the (comma-separated) name(s) of the
		primary key's attributes, or the attributes of a unique index,
		or the name of a unique index on the table. Multiple names in a
		role must be in the same order as they appear in the table or
		respectively in the unique index's argument list.
		<p>
		At the other end, the role must be the name(s) of the foreign key
		attributes.
		<p>
		The types of corresponding primary and foreign key names must be the same.
		<p>
		If the role is omitted at the 'one' end, the primary key
		is used automatically as the attribute name at that end;
		if the role is omitted at the other end, a generated name
		(or names) is used (see Name Generation below).
		<p>
		In the <i>Person</i>/<i>Account</i>/<i>id</i> example above,
		if the role at the 'one' end is omitted it will use <i>id</i>
		as the primary key, and <i>personId</i> as the foreign key
		name if the role name at the 'many' end is omitted.

		<h4>Automatic key generation</h4>
		The <i>-p name:type</i> flag allows the user to omit primary keys
		from the Dia UML diagram; if a primary key is needed in a table, and
		there is no primary key marked in the class, then the primary key
		with the given name and type will be added.
		<p>
		The <i>-f</i> flag allows for the automatic addition of the required
		foreign key columns to the generated tables if the (specified or
		generated) foreign key names do not exist in the class. The generated
		entries take their type from the corresponding primary key names.
		<p>
		The key names are generated using the names as they would be expected
		- if a role name is used, then the generated key uses that name (or names);
		otherwise it uses the automatically generated name(s) as described above.
		<p>
		Automatic key generation works in both ERD and UML modes,
		and allows the user to eliminate much of what is really
		relational DBMS implementation detail from the data
		model diagram.

		<h3>Aggregate/Composition</h3>

		<h4>ERD mode</h4>
		Whichever side is aggregate or composition is the 'many' side in
		the one-to-many relationship. The mode does not distinguish between
		aggregate and composition.
		<p>
		To create a one-to-one relationship, do not make either end of the relationship
		aggregate, but choose the proper direction to decide which is the parent
		table and which the child. I believe, but am not certain today (October 6th 2002)
		that the child table is really either 0 or 1 entry, and the parent 1, so that
		this is really one-to-0,1.

		<h4>UML mode</h4>
		Whichever side is aggregate or composition is the 'one'
		side in the one-to-many relationship.  The multiplicity of
		the other side may be specified in  the usual way.
		<p>
		If the relationship is aggregate, a <code>on delete set
		NULL</code> is added to the foreign key constraint in
		databases that support it; if it is a composition, then
		<code>on delete cascade</code> is added instead.

		<h3>Multiplicity</h3>

		<h4>ERD mode</h4>
		If you would like to add constraint enforcement clauses, such as Oracle:
		<p>
		<code>alter table child add foreign key (idx_iiparent_id) references parent (id) <b>on delete cascade</b>;</code>
		<p>
		Then add the <code>on delete cascade</code> or other constraint
		enforcement into the Multiplicity text box. Currently, this
		constraint enforcement clause is only inserted for InnoDB,
		Postgres and Oracle, but if your DBMS of choice allows this,
		by all means submit a (trivial) patch to generate this syntax.

		<h4>UML mode</h4>
		In UML mode, Multiplicity is just multiplicity. If it is
		explicitly specified, it must be 1 (or 1..1) for the 'one'
		end of an aggregation or composition association.

		<h4>Many-to-many associations</h4>
		Both modes allow the specification of many-to-many relationships.
		They are signified by an unadorned relationship, using the multiplicity
		as it is intended in a UML diagram. The multiplicity of both ends of
		the relation must be specified for the association to be treated as
		many-to-many.
		<p>
		For example, in a more realistic  <i>Person</i>/<i>Account</i>/<i>id</i>
		case where there can be joint accounts, and Persons are not only
		account-holders, specify the Person side as 1..* in the association
		(an Account must have at least one account holder), and the Account
		side as 0..* (Persons are not necessarily account-holders, but may
		have as many accounts as they wish).
		<p>
		A centre (join) table will be generated; its name will be
		PersonAccount (or AccountPerson; the A, or left, name is
		used first), unless the association is named; in which case
		the name of the association is used as the name of the table.
		<p>
		If role names are not used, and the name of the primary key
		in both tables is <i>id</i>, then the table will be generated
		with columns <i>personId</i> and <i>accountId</i>; their
		types are taken from the types of the corresponding primary
		keys. The foreign key constraints in the generated table will
		have an <code>on delete cascade</code> or <code>on delete
		set NULL</code> clause if it is supported by the database.
		<p>
		Role names can be used to control the names of the
		columns in the <em>centre table</em>. The role name has the
		syntax
		[<nbsp><i>fkName</i><nbsp>]<nbsp>[<nbsp><b>:</b><i>pkName</i><nbsp>].
		<p>
		The private key part of the role name names the private key
		attribute(s) (or the name or attribute(s) of a unique index
		on the table) of the class at that (the <i>referring</i>)
		end of the association. This part of the role name would normally
		only be used to refer to a unique index, since the default is to use
		the private key attributes.
		<p>
		The foreign key part of the name at the <em>referring</em>
		end of an association is used to name the column that holds
		the foreign key for the end of the association <em>referred
		to</em>.
		<p>
		For example, if there is a unique index on <i>accountNumber</i>
		in <i>Account</i> and a unique index on <i>ssn</i> in
		<i>Person</i>, then an association between them using the
		indexes instead of the primary keys could be set up with a
		role name <code>:accountNumber</code> at the <i>Account</i>
		end of the association, and <code>:ssn</code> at the <i>Person</i>
		end. If control of the names of the columns in the centre
		(join) table is also required, then the role names might be
		<code>person_ssn:accountNumber</code> at the <i>Account</i>
		end of the association, and <code>account_acNum:ssn</code>
		at the <i>Person</i> end.
		<p>
		The foreign key naming scheme is consistent with the
		convention used for one-to-many relations: The name for the
		foreign key is at the opposite end of the association from
		the table being referred to.

		<h3>One-to-one associations in UML mode</h3>
		Wherever possible UML mode makes use of multiplicity
		to determine the 'owner' end of a foreign key
		relationship. The one instance where this is not possible
		is in an unadorned (i.e. not composition or aggregate)
		one-to-one association. In this case, the same convention
		of using the association direction arrow to indicate
		the 'owner'; the arrow points in the direction of the
		'owner'/table containing the primary key.

		<h3>Views and associations</h3>
		In both modes, many-to-many associations are not permitted
		if either side of the association is a view (marked as
		a UML abstract class).	Otherwise, version 1.2.10 tries
		to generate the same SQL DDL as 1.2.9 where there are
		associations involving views. Both cases probably generate
		bad SQL DDL, since "alter table" (not view) statements
		are generated, and if the view were alterable, then the
		constraints on the underlying base tables should apply.
		<p>
		If the "one" (owner) end of a one-to-many (or one-to-one)
		association is a view, the role must name the "primary
		key". Primary key and foreign key attributes will not be
		automatically generated for views if the <i>-p</i> or
		<i>-f</i> flags are used.

		<h2>Placeholders - For Multi-page and Multi-file Models</h2>
		It can be convenient to lay out large data models so
		that logical parts of them print on single sheets of
		paper, or even to split large models over several files.
		tedia2sql versions from 1.2.10b4 allow the definition
		of "placeholder" classes to make this more convenient
		(and in the case of multi-file models, possible).
		<p>
		A placeholder class is a class with the same name as a
		real class, but with no attributes or operations, and with
		a stereotype <code>&lt;&lt;placeholder&gt;&gt;</code>.
		Any associations between placeholder classes and real
		classes (or even between pairs of placeholders, though
		that is probably poor style) will act as though the
		association with the placeholder class is actually with
		its real class counterpart.
		<p>
		If an association is needed between a class and a
		class on another page, or in another file, create
		a placeholder class on the page where you want to
		place the association, and make the association to the
		placeholder. The association will act as though it refers
		to the corresponding real class.
		<p>
		Overuse of placeholders can probably render data models almost unreadable.
		<p>
		When a placeholder class is processed, in tedia2sql,
		its corresponding real class must be accessible,
		either in the same file, or in another file
		being processed <em>at the same time</em>. If
		<code>a.dia</code> contains class <code>MyClass</code>
		and <code>b.dia</code> contains a placeholder
		<code>&lt;&lt;placeholder&gt;&gt;MyClass</code>,
		then both <code>a.dia</code> and <code>b.dia</code>
		must appear in the argument list of tedia2sql so that
		<code>&lt;&lt;placeholder&gt;&gt;MyClass</code> can be
		processed correctly.

		<h2>UML Components</h2>
		<img src="sampleImages/Component.png" align=right border=1>
		The UML Component is used to insert initial values into
		tables in the SQL DDL. This is useful for codes tables
		and the like. tedia2sql uses the Component 'stereotype'
		as the table that will be inserted into, including columns
		if you don't want to insert all column values. The text
		inside the Component become the list of values that are
		inserted into the table.

		<h3>Stereotype</h3>
		This value simply becomes the table name in the insert
		statement, thusly:
		<pre>
			<i>insert into <b>stereotype</b> values ( . . . )</i>
		</pre>

		<h3>Component Text</h3>
		The text you type in simply become the values to put
		inside the values clause of the insert statement, thusly:
		<pre>
			<i>insert . . . values ( <b>componentText</b> )</i>
		</pre>
		Each newline denotes a new set of values to insert. You
		must specify every column in your table, even if the
		column is nullable or has a default value.  If you want
		to generate a SQL statement thusly:
		<pre>
			<i>insert into <b>stereotype</b> ( col1, col2 ) values ( 1, 2) </i>
		</pre>
		Then you should define your Component stereotype as <i>name ( col1, col2 )</i>
		and define the columns correctly after that.




		<h2>UML SmallPackages</h2>
		<img src="sampleImages/SmallPackage.png" align=right border=1>
		The UML SmallPackage is how tedia2sql inserts
		database-specific SQL that you want to include in your
		schema. This was specifically implemented for dropping
		and creating sequences and triggers, but it could be
		any RDBMS-specific SQL you want.
		<p>
		The SQL can be applied to the database generally, before
		or after ("pre" and "post" stereotypes), or appended
		to tables ("table" stereotypes), indexes ("index"
		stereotypes) and primary keys ("pk" stereotypes).
		<h3>Stereotype</h3>
		This value should be a comma-separated list of the
		databases for which you want to generate the SQL. Use all
		lowercase. Valid values are: <i>sybase</i>, <i>oracle</i>,
		<i>db2</i>, <i>postgres</i>, <i>mysql</i>, <i>mssql</i>,
		<i>informix</i>.  In other words, any string valid to
		pass to the <i>-t</i> option is (once made lowercase)
		valid here.
		<h4>Pre and Post</h4>
		At the end of your comma-separated list of databases,
		you must also put a colon then "pre" or "post" to
		instruct tedia2sql to place these special SQL statements
		<b>before</b> (pre) or <b>after</b> (post) the schema
		(table) statements.
		<p>
		Typically, sequences would be :pre statements, and
		triggers would be :post.
		<p>
		The Stereotype might be "oracle,postgres:pre" meaning put
		these SQL statements before the table create statements,
		and put this SQL only for Oracle and Postgres databases.

		<h4>Table</h4>
		Adds the SmallPackage text as SQL statements between
		the closing ")" of the table column definitions
		and the <i>create table</i> statement end.
		After the comma-separated list of databases, put
		<code>:table</code>, and then a comma-separated list of
		table names (including generated table names), enclosed
		in parentheses, that are to have the extra clauses added.
		<p>
		For example, a Sterotype
		<code>oracle:table(Person,Account)</code> could be used to
		add a storage clause to the Person and Account tables for
		the example above.
		<p>
		<pre>
		&lt;&lt;oracle:table(Person,Account)&gt;&gt;
		    storage (initial 10M next 1M pctincrease 0)
		</pre>
		<p>

		<h4>Index</h4>
		Adds the SmallPackage text as SQL statements between the
		closing ")" of the column name list and the <i>create
		index</i> statement end. Similar syntax to the table
		specification, but use <code>:index</code> and the list
		of names is the list of index names that are to have
		the extra SQL clauses.

		<h4>Primary Key</h4>
		Adds the SmallPackage text as SQL statements between
		the closing ")" of the primary key name list and the
		<i>constraint</i> statement end. Similar syntax to the
		table specification, but use <code>:pk</code> and the
		list of names is the list of table names that are to
		have the extra SQL clauses.

		<h4>Columns</h4>
		Adds the SmallPackage text to the column definition
		part of the named tables. The text is inserted
		after the column definitions and the primary key
		constraint (if there is one), and just before the
		closing parenthesis. Use <code>:columns</code> in the
		SmallPackage name. For example, to check the <i>type</i>
		column of <i>PersonType</i>:
		<p>
		<pre>
		&lt;&lt;oracle:columns(PersonType)&gt;&gt;
		constraint perstype_type
		    check (lower(type)) in ('staff', 'accountholder', 'other')
		</pre>

		<h3>SmallPackage Text</h3>
		For all of the above, this text is passed as-is into the SQL
		DDL. Thus, you must create valid SQL for the RDBMSs you put
		into Stereotype into this area.

		<h3>Type map</h3>
		A "typemap" stereotype can be used to remap types used in
		the UML diagram to types used in the generated SQL. The
		type map itself is in the SmallPackage text and is a list
		of semicolon-separated type definitions, with the base type
		on the left of a colon, and a comma-separated list of new
		defined types on the right. The database name list makes the
		mapping specific to the databases listed.
		<p>
		<pre>
		&lt;&lt;oracle: typemap&gt;&gt;
		integer: number(10);
		string, character: varchar2;
		fixed3: number(25.3);
		</pre>
		<p>
		The interpretation is recursive (a type may be defined
		in terms of another defined type), and because the
		interpretation doesn't occur until after all types have
		been defined, may be in any order. The interpretation
		stops when no further mappings are applicable, which
		means that if a typemap entry does not exist for a type,
		the type in the UML is passed through unchanged to the
		SQL. To guard against infinite recursion the number of
		mappings to remap any single type is limited to about 100.
		<p>
		Type interpretation occurs <i>late</i>; only when the
		SQL statements are being generated. For other purposes,
		only the user types are considered. For example,
		for checking the types of foreign vs private keys in a
		relationship, tedia2sql will consider <code>integer</code>
		and <code>number(10)</code> to be <i>different</i>
		types even if you use the <code>typemap</code> above.

		<h2>Class and Attribute Comments</h2>
		Version 0.91 (and later) of dia allows comments in classes and on
		class attributes. Class comments (in the Class tab of
		the Class Properties popup window) are passed through
		into the generated SQL - placed just before the table
		definition for the class. Class attribute comments
		(in the Attributes tab of Class Properties popup window)
		are placed inline after the row in the table definition
		that corresponds to the attribute.
		<p>
		The implementation of this feature allows classes and
		attributes to not have <code>&lt;comment&gt;</code> attributes
		in the dia files, so it is backward-compatible with pre 0.91
		files that do not have comments on classes.
		<p>
		UML Notes text is not passed through to the SQL, though
		that would probably be useful.

		<h2>Name Generation</h2>
		The name generation code in tedia2sql follows a fairly
		simple set of rules.

		<h3>Table Names</h4>
		The only generated table names are for centre
		(join) tables in many-to-many associations. They are
		constructed by concatenating class name on the left
		(dia 'A') side with the class name on the right (dia
		'B') side of the association. The left side name is
		unmodified; the first character of the right side name
		is capitalised.  So an unnamed many-to-many association
		between <code>person</code> and <code>account</code> would
		have a centre table named <code>personAccount</code>.
		<p>
		The automatic name generation can be overridden by naming
		the association.
		
		<h3>Foreign Key Names</h3>
		A foreign key name is generated from the name of the
		class that it refers <i>to</i> and the name of the
		(element of) the primary key of that class.
		<p>
		Any leading capitalised part of the class name
		is converted to lower case, and the first part of the
		primary key name is capitalised. The "leading capitalised
		part" is either a single capital at the start, or the
		string of all but the last capitals if there are more
		than one: the leading capitalised part of the class
		name <code>UKPrimeMinisters</code> is <code>UK</code>
		(not <code>UKP</code>).
		<p>
		In the example many-to-one relationship
		<code>Account</code> to <code>Person</code> (a person
		may have multiple accounts, but there are no joint
		accounts), if the primary key of <code>Person</code>
		is <code>id</code>, then the generated foreign key name
		for the relationship is <code>personId</code>.

		<h3>Primary key constraint names</h3>

		Primary key constraint names are built by prefixing the
		string <code>pk_</code> to the capitalised class name.The
		primary key constraint name for <code>Person</code>
		is <code>pk_Person</code>. This rule is followed for
		the constraint names in tables with generated names.

		<h3>Foreign key constraint names</h3>
		Foreign key constraint names are generated by
		concatenating the lower-cased (as for the leading part
		of foreigh key names) <i>referenced</i> class name, the
		string <code>_fk_</code>, the capitalised class name of
		the <i>referencing</i> class, followed by the capitalised
		name (of the first element of) the primaty key of the
		referenced class; this part after the <code>_fk_</code>
		is essentially the capitalised name of the foreign key.
		
		<h3>Name shortening</h3>
		If a generated name is too long, it is shortened to the
		maximum name allowed by the DBMS.
		<p>
		The name is first shortened by removing vowels from the name;
		part at a time, starting with the first part.
		<p>
		If this is insufficient, the centre of each of the
		parts of the name is taken out. Up to this point, names
		remain more-or-less comprehensible.
		<p>
		If the name is <i>still</i>, a base-64 MD5 checksum
		is constructed for the whole name and that is used
		for the name of the table (shortened if necessary by
		truncation). This results in a most-likely-unique,
		but incomprehensible, name.
		
		<h3><i>De gustibus non disputandum est</i></h3>
		Name conventions in programming are a matter of
		taste. What's been implemented suits the author of the
		name generation code and the project he's working on. It
		may not suit you.
		<p>
		If it doesn't, the code for name generation is all in
		<code>sub makeName</code>, please feel free to add code
		to suit other name generation conventions with suitable
		switches for enabling it. Try not to change the code in
		ways that might change the table names or column names
		in existing DIAgrams.

	</body>
</html>