Database Naming Conventions Common Network Information Service Editors: Paweł Gruszczyński PSNC, Damian Mierzwiński PSNC 1. Introduction The aim of this document is to present database naming conventions used in cNIS project. First part of this document describe standard naming conventions used in relational databases. Second part confront this standard approach with cNIS conventions based on Hibernate ORM tool. Last section provide short recommendations for developers of cNIS project. This document is dedicated for a wide audience, including developers, programmers, people who are responsible for tests and authors of the software documentation. 2. Standard naming conventions 2.1 Tables 2.1.1 Plural Names Table names should be plural. For table names with multiple words, only the last word should be plural. 2.1.2 Prefixes Table prefixes can help organize tables into related groups or distinguish them from other unrelated tables. Avoid prefixes like "tbl" or "TBL_" as these are just redundant and unnecessary. 2.1.3 Notation Table name: should be lowercased for word separator and prefixes '_' sign should be used should not contain numbers should not contain spaces. 2.1.4 Junction (Intersection Tables) Junction tables, which handle many to many relationships, should be named by concatenating the names of the tables (with '_' separator) that have a one to many relationship with the junction table. Since this convention can result in lengthy table names, abbreviations sometimes may be used at your discretion. 2.1.5 Other Table Naming Conventions Use short, unambiguous names, using no more than one or two words. Avoid abbreviated, concatenated, or acronymic names. 1 2.2 Columns Columns are members of the table, so they do not need the any mention of the table name in the name. The primary key field is typically the only exception to this rule where including the table name is justified so that you can have a more descriptive field name than just "id". Just like with naming tables, avoid using abbreviations, acronyms or special characters. All column names should use lowercased with '_' as word separator. 2.2.1 Identity Primary Key Fields The primary key should be the singular table name suffixed with "_id". 2.2.2 Foreign Key Fields Foreign key fields should have the same name as the primary key to which they refer. If foreign key field is also primary key, then primary key rule is used. 2.2.3 Prefixes Fields should not by prefixed with "fld_" or "col_" as it should be obvious in SQL statements which items are columns (before or after the FROM clause). 2.2.4 Data Type Specific Naming Boolean fields should be given names like "is_deleted", "has_permission", or "is_valid" so that the meaning of the data in the field is not ambiguous. If the field holds date and/or time information, the word "date" or "time" should appear somewhere in the field name. It is sometimes appropriate to add the unit of time to the field name also, especially if the field holds data like whole numbers. 2.3 Indexes Since indexes are always related to a table or view, it makes the most sense to use the name of the table or view, as well as the column(s) they index, in the index name, along with some characters that specify the type of index it is. This naming convention also allows, if looking at a list of indexes, to see the indexes ordered by table, then column, then index type. 2.3.1 Naming Convention The naming convention for indexes follows this structure: {table_name}_{columns_indexed}{U/N} where "U/N" is for unique or non-unique. This naming convention is unique among database objects, so adding characters to denote it being an index, like "idx" is not necessary. The naming convention alone is self-documenting and identifies it as an index. For indexes that span multiple columns, concatenate the column names. If name is too long use abbreviations for column names. 2.4 Constraints Constraints are at the field/column level so the name of the field the constraint is on should be used in the name. The type of constraint (Check, Referential Integrity a.k.a Foreign Key, Primary Key, or Unique) should be noted also. Constraints are also unique to a particular table and field combination, so you should include the table name also to ensure unique constraint names across your set of database tables. 2 2.4.1 Naming Convention The naming convention syntax for constraints looks like this: {constraint_type}_{table name}_{field name}. 2.4.2 Prefixes A two letter prefix gets applied to the constraint name depending on the type. Constraint type Prefix Primary Key pk Foreign Key fk Check ck Unique un 2.5 Views Views follow many of the same rules that apply to naming tables. 2.5.1 Prefixes View name should be prefixed with "vw_". 2.5.2 View Types Naming views should be different depending on the type or purpose of the view. For simple views that just join two or more tables with no selection criteria, view name should be combined of names of the tables joined (also just name of the main table prefixed with "vw_" could be used). 3. cNIS naming conventions cNIS use Hibernate (version 3.2.6.ga) as data access library. Hibernate provide default naming conventions which directly maps classes and properties names to tables and columns names without any changes. To override this behaviour cNIS use org.hibernate.cfg.ImprovedNamingStrategy implementation of naming strategy which is very close to the standard approach. Next sections compares ImprovedNamingStrategy with the standard one. 3.1 Tables 3.1.1 Singular Names Table names are generated automatically and are in the singular form. This simplifies the overall Hibernate configuration and its maintenance. Words from the class name are split with underscores and converted to lower case, e.g.: NodeVersion class will be associated with table named node_version. 3.1.2 Junction (Intersection Tables) Intersection tables are used to map many-to-many relations. The name of the intersection table is specified by table attribute of the set element in Hibernate mapping files. Those names should follow standard naming conventions. 3 3.2 Columns Table column names are generated automatically alike table names. Java persisted classes properties in cNIS follow the standard naming convention, e.g.: isVirtual, dateCreated, etc. 3.3 Indexes Indexes are associated with one-to-many relations mapping and Java Map objects mapping. Name of the index is specified by the index attribute and should follow standard naming conventions for indexes. 3.4 Constrains Constrains names are automatically generated by Hibernate tool and do not follow the standard naming conventions. Primary key constraint name consists of a table name suffixed by “_pkey” string. Other constraints are named randomly, according to the database policy. 3.5 Views There are no views in the cNIS database schema. 4. Recommendations It is recommended to use described here standard naming conventions when writing persistent entities classes. Moreover, developers should be aware about Hibernate naming conventions implementation used in cNIS (ImprovedNamingStrategy) and leave word splitting and underscores inserting to Hibernate when it is only possible. 4