Document DB Schema

[KT Walrus]

I like how you documented Error Codes in the Customer Resources section.

Could you add similar documentation for all DB tables and columns?

It would really help if there was a quick reference where I could look up a table or column in the database and see a description of what purpose the element serves, when, where, and why it is created, read, updated, and destroyed.

With code like IP.Board, such schema documentation would go a long way to explaining exactly how the DB is used and help us in writing mods that do the write thing, especially if you include the methods that are public that affect the table or columns.

Similarly, it would be nice to document all public methods that could be called by new code in a similar fashion. But, the DB schema documentation is the most needed. A few of the columns seem to have names that don't really fit their current usage (I suspect this is because they started out life as something else, but then as the software has evolved, their function changed but you were reluctant to rename the actual column for easy upgrades).

[Matt]

I did do this for the member's table. It's under the Log in category in the dev docs.

[Brett B]

Maybe also for system settings? For example, which value to change and where if you want to turn your board off via phpMyAdmin if the board is inaccessible.

[Mark]

[quote name='Brett B' date='30 September 2009 - 04:22 PM' timestamp='1254324146' post='1862379']
Maybe also for system settings? For example, which value to change and where if you want to turn your board off via phpMyAdmin if the board is inaccessible.


Settings are cached - you can't just change the value in phpMyAdmin.

[Brett B]

Well that would explain why when I tried nothing happened. I could have sworn that I've read someone talking about turning the board offline remotely.

[rct2·com]

You used to be able to turn the board offline by editing conf_global.php. Perhaps that what you remember?

[KT Walrus]

[quote name='Matt' date='30 September 2009 - 11:01 AM' timestamp='1254322912' post='1862367']
I did do this for the member's table. It's under the Log in category in the dev docs.


I'm looking for a bit more detail then this. Short descriptions about the column are not all that helpful. I want the where, what, when, and why the column exists. The information should be at least a small paragraph and might be an entire page.

You really can't understand an application unless you understand the data it stores and how it operates on that data.

[bfarber]

I'd venture to say it's unrealistic to expect that we'll ever write that sort of detailed documentation on every table and column in IPB. While I wouldn't have a problem doing it, I don't personally have the time to do such a thing at this time (and I'm sure all of the developers will say the same).

[Brett B]

[quote name='tired of being rct2dotcom' date='30 September 2009 - 06:23 PM' timestamp='1254349424' post='1862528']
You used to be able to turn the board offline by editing conf_global.php. Perhaps that what you remember?

Could be. Is that still possible?

[Matt]

As per Brandon. I could probably write a short note of what each field is for for most of the common tables, but it's a huge ask to go into deep detail on every field and table and to note exactly where it's used. By the time we've finished it it'll probably be out of date.

In most cases, I'd venture that you can probably figure it out from the table name and field name. Granted, we do have some odd esoteric fields that are mostly legacy issues but on the whole it's fairly verbose as is.