Dan Langille wrote: > > On Feb 4, 2009, at 5:50 PM, Kevin Keane wrote: > >> Here is a second feature request >> >> Item n: Document the database design >> Origin: Kevin Keane, subscript...@kkeane.com >> Date: February 4, 2009 >> Status: >> >> What: I would like to see a complete documentation of all the >> database tables. > > "Complete" is subjective. > > What do you define as complete? The single most important part of such documentation would be an ERD of the database. In fact, for me personally, that would probably be enough to figure out the rest. Secondarily: Describing the fundamental design philosophy behind the database (what kinds of items are being represented, how are they connected to each other?) A list of all tables, along with their foreign keys. A list of all fields in each table A description of the meaning of each field (from a user perspective, not a technical description) When a field is constrained, a list of the permissible values or whatever the constraint is.
All of that should be in the user documentation, not just in the developer documentation - because bconsole is a user tool. Ultimately, though, my favorite would be to remove the sqlquery command altogether, and have more specific commands that do what users really want it to do. Users shouldn't have to dig through SQL code to solve their problems any more than they should have to dig through C/C++ code. > What is missing that you want to see? I wouldn't even know where to find a list of the tables or how they relate to each other. > When we start the documentation, how can we tell when we're done? Ah, the age-old question of technical writers ;-) Ultimately, you can't. Just do the best you can. >> Why: bconsole has the command "sqlquery" but without knowing what >> to query for, it is fairly useless. >> >> Notes: Many common queries are accessible via the "query" command, >> which completely hides the database. But query is limited to those few >> predefined queries. >> >> Alternatively, instead of documenting the database, maybe it would be >> better to remove the command "sqlquery" completely, since it is also >> easy to abuse (what's to stop somebody from doing insert or update >> queries?) Those people who really do need such low-level functionality >> can use mysql or postgres directly. -- Kevin Keane Owner The NetTech Find the Uncommon: Expert Solutions for a Network You Never Have to Think About Office: 866-642-7116 http://www.4nettech.com This e-mail and attachments, if any, may contain confidential and/or proprietary information. Please be advised that the unauthorized use or disclosure of the information is strictly prohibited. The information herein is intended only for use by the intended recipient(s) named above. If you have received this transmission in error, please notify the sender immediately and permanently delete the e-mail and any copies, printouts or attachments thereof. ------------------------------------------------------------------------------ Create and Deploy Rich Internet Apps outside the browser with Adobe(R)AIR(TM) software. With Adobe AIR, Ajax developers can use existing skills and code to build responsive, highly engaging applications that combine the power of local resources and data with the reach of the web. Download the Adobe AIR SDK and Ajax docs to start building applications today-http://p.sf.net/sfu/adobe-com _______________________________________________ Bacula-users mailing list Bacula-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/bacula-users
