From lspevak at redhat.com Tue Feb 26 07:36:40 2013 Content-Type: multipart/mixed; boundary="===============8049637400164142938==" MIME-Version: 1.0 From: Libor Spevak To: devel at ovirt.org Subject: [Engine-devel] Engine table comments Date: Tue, 26 Feb 2013 13:37:17 +0100 Message-ID: <512CAC7D.2060900@redhat.com> --===============8049637400164142938== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable This is a multi-part message in MIME format. --------------090900020406030601070406 Content-Type: text/plain; charset=3DISO-8859-1; format=3Dflowed Content-Transfer-Encoding: 7bit Hi, I would like to propose to create a patch assigning sql comment to each = Engine table. The comments will be a part of the exported DB schema report, too. The terminology is not always consistent across all application layers, = so for the newcomers it would be easier to understand the model. But, what would be general guidelines? I recommend to use singular form of entity name as used from end-user = point of view (if somehow visible, of course), or just used frequently = inside code. Examples: storage_pool ... Data center vds_groups ... Cluster but: vm_static ... Virtual machine configuration vm_dynamic ... Virtual machine runtime data vm_statistics ... Virtual machine statistics data ... etc. This command prepares a template for the patch: /psql engine -U postgres -c "select 'COMMENT ON TABLE ' || relname || ' = IS ''TODO'';' sql from pg_stat_user_tables t WHERE schemaname=3D'public' = order by t.relname" > comments_to_do.sql// / or just I can prepare a page on the wiki with table containing table = names and volunteers :-) can propose simple understandable comments for = known tables. Is it useful? Thanks. Regards, Libor --------------090900020406030601070406 Content-Type: text/html; charset=3DISO-8859-1 Content-Transfer-Encoding: 7bit Hi,
I would like to propose to create a patch assigning sql comment to each Engine table.
The comments will be a part of the exported DB schema report, too.
The terminology is not always consistent across all application layers, so for the newcomers it would be easier to understand the model.

But, what would be general guidelines?

I recommend to use singular form of entity name as used from end-user point of view (if somehow visible, of course), or just used frequently inside code.

Examples:
storage_pool ... Data center
vds_groups ... Cluster
but:
vm_static  ... Virtual machine configuration
vm_dynamic ... Virtual machine runtime data
vm_statistics ... Virtual machine statistics data
...
etc.

This command prepares a template for the patch:

psql engine -U postgres -c "select 'COMMENT ON TABLE ' || relname || ' IS ''TODO'';' sql from pg_stat_user_tables t WHERE schemaname=3D'public' order by t.relname" > comments_to_do.sql=

or just I can prepare a page on the wiki with table containing table names and volunteers :-) can propose simple understandable comments for known tables.

Is it useful?

Thanks.

Regards,
Libor
--------------090900020406030601070406-- --===============8049637400164142938== Content-Type: multipart/alternative MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="attachment.bin" VGhpcyBpcyBhIG11bHRpLXBhcnQgbWVzc2FnZSBpbiBNSU1FIGZvcm1hdC4KLS0tLS0tLS0tLS0t LS0wOTA5MDAwMjA0MDYwMzA2MDEwNzA0MDYKQ29udGVudC1UeXBlOiB0ZXh0L3BsYWluOyBjaGFy c2V0PUlTTy04ODU5LTE7IGZvcm1hdD1mbG93ZWQKQ29udGVudC1UcmFuc2Zlci1FbmNvZGluZzog N2JpdAoKSGksCkkgd291bGQgbGlrZSB0byBwcm9wb3NlIHRvIGNyZWF0ZSBhIHBhdGNoIGFzc2ln bmluZyBzcWwgY29tbWVudCB0byBlYWNoIApFbmdpbmUgdGFibGUuClRoZSBjb21tZW50cyB3aWxs IGJlIGEgcGFydCBvZiB0aGUgZXhwb3J0ZWQgREIgc2NoZW1hIHJlcG9ydCwgdG9vLgpUaGUgdGVy bWlub2xvZ3kgaXMgbm90IGFsd2F5cyBjb25zaXN0ZW50IGFjcm9zcyBhbGwgYXBwbGljYXRpb24g bGF5ZXJzLCAKc28gZm9yIHRoZSBuZXdjb21lcnMgaXQgd291bGQgYmUgZWFzaWVyIHRvIHVuZGVy c3RhbmQgdGhlIG1vZGVsLgoKQnV0LCB3aGF0IHdvdWxkIGJlIGdlbmVyYWwgZ3VpZGVsaW5lcz8K CkkgcmVjb21tZW5kIHRvIHVzZSBzaW5ndWxhciBmb3JtIG9mIGVudGl0eSBuYW1lIGFzIHVzZWQg ZnJvbSBlbmQtdXNlciAKcG9pbnQgb2YgdmlldyAoaWYgc29tZWhvdyB2aXNpYmxlLCBvZiBjb3Vy c2UpLCBvciBqdXN0IHVzZWQgZnJlcXVlbnRseSAKaW5zaWRlIGNvZGUuCgpFeGFtcGxlczoKc3Rv cmFnZV9wb29sIC4uLiBEYXRhIGNlbnRlcgp2ZHNfZ3JvdXBzIC4uLiBDbHVzdGVyCmJ1dDoKdm1f c3RhdGljICAuLi4gVmlydHVhbCBtYWNoaW5lIGNvbmZpZ3VyYXRpb24Kdm1fZHluYW1pYyAuLi4g VmlydHVhbCBtYWNoaW5lIHJ1bnRpbWUgZGF0YQp2bV9zdGF0aXN0aWNzIC4uLiBWaXJ0dWFsIG1h Y2hpbmUgc3RhdGlzdGljcyBkYXRhCi4uLgpldGMuCgpUaGlzIGNvbW1hbmQgcHJlcGFyZXMgYSB0 ZW1wbGF0ZSBmb3IgdGhlIHBhdGNoOgoKL3BzcWwgZW5naW5lIC1VIHBvc3RncmVzIC1jICJzZWxl Y3QgJ0NPTU1FTlQgT04gVEFCTEUgJyB8fCByZWxuYW1lIHx8ICcgCklTICcnVE9ETycnOycgc3Fs IGZyb20gcGdfc3RhdF91c2VyX3RhYmxlcyB0IFdIRVJFIHNjaGVtYW5hbWU9J3B1YmxpYycgCm9y ZGVyIGJ5IHQucmVsbmFtZSIgPiBjb21tZW50c190b19kby5zcWwvLwovCm9yIGp1c3QgSSBjYW4g cHJlcGFyZSBhIHBhZ2Ugb24gdGhlIHdpa2kgd2l0aCB0YWJsZSBjb250YWluaW5nIHRhYmxlIApu YW1lcyBhbmQgdm9sdW50ZWVycyA6LSkgY2FuIHByb3Bvc2Ugc2ltcGxlIHVuZGVyc3RhbmRhYmxl IGNvbW1lbnRzIGZvciAKa25vd24gdGFibGVzLgoKSXMgaXQgdXNlZnVsPwoKVGhhbmtzLgoKUmVn YXJkcywKTGlib3IKCi0tLS0tLS0tLS0tLS0tMDkwOTAwMDIwNDA2MDMwNjAxMDcwNDA2CkNvbnRl bnQtVHlwZTogdGV4dC9odG1sOyBjaGFyc2V0PUlTTy04ODU5LTEKQ29udGVudC1UcmFuc2Zlci1F bmNvZGluZzogN2JpdAoKPGh0bWw+CiAgPGhlYWQ+CgogICAgPG1ldGEgaHR0cC1lcXVpdj0iY29u dGVudC10eXBlIiBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9SVNPLTg4NTktMSI+CiAgPC9o ZWFkPgogIDxib2R5IGJnY29sb3I9IiNGRkZGRkYiIHRleHQ9IiMwMDAwMDAiPgogICAgSGksIDxi cj4KICAgIEkgd291bGQgbGlrZSB0byBwcm9wb3NlIHRvIGNyZWF0ZSBhIHBhdGNoIGFzc2lnbmlu ZyBzcWwgY29tbWVudCB0bwogICAgZWFjaCBFbmdpbmUgdGFibGUuPGJyPgogICAgVGhlIGNvbW1l bnRzIHdpbGwgYmUgYSBwYXJ0IG9mIHRoZSBleHBvcnRlZCBEQiBzY2hlbWEgcmVwb3J0LCB0b28u PGJyPgogICAgVGhlIHRlcm1pbm9sb2d5IGlzIG5vdCBhbHdheXMgY29uc2lzdGVudCBhY3Jvc3Mg YWxsIGFwcGxpY2F0aW9uCiAgICBsYXllcnMsIHNvIGZvciB0aGUgbmV3Y29tZXJzIGl0IHdvdWxk IGJlIGVhc2llciB0byB1bmRlcnN0YW5kIHRoZQogICAgbW9kZWwuPGJyPgogICAgPGJyPgogICAg QnV0LCB3aGF0IHdvdWxkIGJlIGdlbmVyYWwgZ3VpZGVsaW5lcz88YnI+CiAgICA8YnI+CiAgICBJ IHJlY29tbWVuZCB0byB1c2Ugc2luZ3VsYXIgZm9ybSBvZiBlbnRpdHkgbmFtZSBhcyB1c2VkIGZy b20KICAgIGVuZC11c2VyIHBvaW50IG9mIHZpZXcgKGlmIHNvbWVob3cgdmlzaWJsZSwgb2YgY291 cnNlKSwgb3IganVzdCB1c2VkCiAgICBmcmVxdWVudGx5IGluc2lkZSBjb2RlLjxicj4KICAgIDxi cj4KICAgIEV4YW1wbGVzOjxicj4KICAgIHN0b3JhZ2VfcG9vbCAuLi4gRGF0YSBjZW50ZXI8YnI+ CiAgICB2ZHNfZ3JvdXBzIC4uLiBDbHVzdGVyPGJyPgogICAgYnV0Ojxicj4KICAgIHZtX3N0YXRp YyZuYnNwOyAuLi4gVmlydHVhbCBtYWNoaW5lIGNvbmZpZ3VyYXRpb248YnI+CiAgICB2bV9keW5h bWljIC4uLiBWaXJ0dWFsIG1hY2hpbmUgcnVudGltZSBkYXRhPGJyPgogICAgdm1fc3RhdGlzdGlj cyAuLi4gVmlydHVhbCBtYWNoaW5lIHN0YXRpc3RpY3MgZGF0YTxicj4KICAgIC4uLjxicj4KICAg IGV0Yy48YnI+CiAgICA8YnI+CiAgICBUaGlzIGNvbW1hbmQgcHJlcGFyZXMgYSB0ZW1wbGF0ZSBm b3IgdGhlIHBhdGNoOjxicj4KICAgIDxicj4KICAgIDxpPnBzcWwgZW5naW5lIC1VIHBvc3RncmVz IC1jICJzZWxlY3QgJ0NPTU1FTlQgT04gVEFCTEUgJyB8fCByZWxuYW1lCiAgICAgIHx8ICcgSVMg JydUT0RPJyc7JyBzcWwgZnJvbSBwZ19zdGF0X3VzZXJfdGFibGVzIHQgV0hFUkUKICAgICAgc2No ZW1hbmFtZT0ncHVibGljJyBvcmRlciBieSB0LnJlbG5hbWUiICZndDsgY29tbWVudHNfdG9fZG8u c3FsPC9pPjxpPjxicj4KICAgIDwvaT48YnI+CiAgICBvciBqdXN0IEkgY2FuIHByZXBhcmUgYSBw YWdlIG9uIHRoZSB3aWtpIHdpdGggdGFibGUgY29udGFpbmluZyB0YWJsZQogICAgbmFtZXMgYW5k IHZvbHVudGVlcnMgOi0pIGNhbiBwcm9wb3NlIHNpbXBsZSB1bmRlcnN0YW5kYWJsZSBjb21tZW50 cwogICAgZm9yIGtub3duIHRhYmxlcy48YnI+CiAgICA8YnI+CiAgICBJcyBpdCB1c2VmdWw/PGJy PgogICAgPGJyPgogICAgVGhhbmtzLjxicj4KICAgIDxicj4KICAgIFJlZ2FyZHMsPGJyPgogICAg TGlib3I8YnI+CiAgPC9ib2R5Pgo8L2h0bWw+CgotLS0tLS0tLS0tLS0tLTA5MDkwMDAyMDQwNjAz MDYwMTA3MDQwNi0tCg== --===============8049637400164142938==--