Many database systems don’t allow comments or descriptions of tables and fields, so how do you go about documenting the purpose of a table/field apart from the obvious of having good naming conventions?
(Let’s assume for now that ‘excellent’ table and field names are not enough to document the full meaning of every table, field and relationship in the database.)
I know many people use UML diagrams to visualize the database, but I have rarely—if ever—seen a UML diagram including field comments. However, I have good experience with using comments inside .sql files. The downside to this approach is that it requires the .sql files to be manually kept up-to-date as the database structure changes over time—but if you do, you can also have it under version control.
Some other techniques I have seen are separate document describing database structure and relationships and manually maintained comments inside ORM code or other database-mapping code.
How have you solved this problem in the past? What methods exists and what are the various pros and cons associated with them? How you would you like this solved in ‘a perfect world’?
Update
As others have pointed out, most of the popular SQL engines do in fact allow comments, which is great. Oddly enough, people don’t seem to be using these features much. At least not on the projects I have been involved with in the past.
MySQL allows comments on tables and rows. PostgreSQL does as well. From other answers, Oracle and MSSQL have comments too.
For me, a combination of UML diagram for a quick refresher on field names, types, and constraints, and an external document (TeX, but could be any format) with extended description of everything database-related – special values, field comments, access notes, whatever – works best.