Missing COMMENT ON POLICY

Started by Charles Clavadetscherover 10 years ago11 messages

clavadetscher@swisspug.org

over 10 years ago

Hello

Lately I am working intensively with the documentation capabilities of
PostgreSQL and I noticed that, although the functionality is available in
9.5 to add a comment to a policy, there is no entry for in the documentation

http://www.postgresql.org/docs/9.5/static/sql-comment.html

Probably it would look like:

COMMENT ON POLICY policy_name ON table_name |

Between
OPERATOR FAMILY object_name USING index_method | and
[ PROCEDURAL ] LANGUAGE object_name |

Regards
Charles

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Charles Clavadetscher (#1)

1 attachment(s)

[DOCS] Missing COMMENT ON POLICY

Hello

Well I gave it a try. I am still not very well aware how the process for
suggesting or submitting corrections work, but this is as far as I got.
In the attachment is a patch for the missing entry for POLICY in the
documentation on COMMENT that I mentioned earlier on pgsql-docs.

Hope this helps.

Regards
Charles

-----Original Message-----
From: pgsql-docs-owner@postgresql.org
[mailto:pgsql-docs-owner@postgresql.org] On Behalf Of Charles Clavadetscher
Sent: Sonntag, 13. September 2015 07:36
To: pgsql-docs@postgresql.org
Subject: [DOCS] Missing COMMENT ON POLICY

Hello

http://www.postgresql.org/docs/9.5/static/sql-comment.html

Probably it would look like:

COMMENT ON POLICY policy_name ON table_name |

Between
OPERATOR FAMILY object_name USING index_method | and
[ PROCEDURAL ] LANGUAGE object_name |

Regards
Charles

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Attachments:

comment_on_policy.patchapplication/softgrid-patch; name=comment_on_policy.patchDownload

commit 0327154ba838894ccfb3420daed94b9832fd8bfa
Author: Charles Clavadetscher <clavadetscher@swisspug.org>
Date:   Sun Sep 13 08:08:00 2015 +0200

    Added POLICY to list of COMMENT ON objects.

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 1030738..2133e77 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -43,6 +43,7 @@ COMMENT ON
   OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) |
   OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
   OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
+  POLICY <replaceable class="PARAMETER">policy_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
   ROLE <replaceable class="PARAMETER">object_name</replaceable> |
   RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |

Stephen Frost

sfrost@snowman.net

over 10 years ago

In reply to: Charles Clavadetscher (#2)

Re: [DOCS] Missing COMMENT ON POLICY

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Well I gave it a try. I am still not very well aware how the process for
suggesting or submitting corrections work, but this is as far as I got.
In the attachment is a patch for the missing entry for POLICY in the
documentation on COMMENT that I mentioned earlier on pgsql-docs.

Thanks! This looks mostly correct but only goes half-way (not that
there's a lot to this change ;). The 'policy_name' parameter which is
added should also be added to the 'Parameters' list below, and the
description under 'table_name' updated to reflect that it's used for
policies also.

There should probably be an example added also, since it looks like
there are examples of pretty much all the other COMMENT ON
types.

Thanks again!

Stephen

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Stephen Frost (#3)

Re: [DOCS] Missing COMMENT ON POLICY

Hello Stephen

Yes, of course. I will take care of that and send a new patch.
Who will then git push it?

Thank you for your feedback.
Bye
Charles

-----Original Message-----
From: pgsql-hackers-owner@postgresql.org [mailto:pgsql-hackers-
owner@postgresql.org] On Behalf Of Stephen Frost
Sent: Sonntag, 13. September 2015 14:31
To: Charles Clavadetscher <clavadetscher@swisspug.org>
Cc: pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] [DOCS] Missing COMMENT ON POLICY

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Well I gave it a try. I am still not very well aware how the process for
suggesting or submitting corrections work, but this is as far as I got.
In the attachment is a patch for the missing entry for POLICY in the
documentation on COMMENT that I mentioned earlier on pgsql-docs.

Thanks! This looks mostly correct but only goes half-way (not that
there's a lot to this change ;). The 'policy_name' parameter which is
added should also be added to the 'Parameters' list below, and the
description under 'table_name' updated to reflect that it's used for
policies also.

There should probably be an example added also, since it looks like
there are examples of pretty much all the other COMMENT ON
types.

Thanks again!

Stephen

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Stephen Frost

sfrost@snowman.net

over 10 years ago

In reply to: Charles Clavadetscher (#4)

Re: [DOCS] Missing COMMENT ON POLICY

Charles,

Just FYI, on these lists, we'd prefer it if you wouldn't top-post.

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Yes, of course. I will take care of that and send a new patch.

Thanks!

Who will then git push it?

I'd be happy to take care of it, though any of the committers may pick
it up, of course. If there's a concern about the patch being missed or
forgotten then it can be added to the commitfest system (here:
http://commitfest.postgresql.org). I don't believe there's a risk of
that here, but you're welcome to add it if you'd like, of course.

Thank you for your feedback.

Thank you for working on this!

Stephen

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Stephen Frost (#5)

2 attachment(s)

Re: [DOCS] Missing COMMENT ON POLICY

Hello Stephen

On 13/09/2015 14:49, Stephen Frost wrote:

Charles,

Just FYI, on these lists, we'd prefer it if you wouldn't top-post.

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Yes, of course. I will take care of that and send a new patch.

Thanks!

Who will then git push it?

I'd be happy to take care of it, though any of the committers may pick
it up, of course. If there's a concern about the patch being missed or
forgotten then it can be added to the commitfest system (here:
http://commitfest.postgresql.org). I don't believe there's a risk of
that here, but you're welcome to add it if you'd like, of course.

Thank you for your feedback.

Thank you for working on this!

Stephen

In the attachement the new patch. I was not able to create one with both
commits so I also added the first one.
I think that documentation should be as complete as possible, but if you
say that there is no risk in missing the update, then I don't see a need
to add a line in the commitfest.

Thank you also for the hint on top-posting. I was not aware of that.
Have a good Sunday.
Charles

Attachments:

comment_on_policy.patchapplication/softgrid-patch; name=comment_on_policy.patchDownload

commit 0327154ba838894ccfb3420daed94b9832fd8bfa
Author: Charles Clavadetscher <clavadetscher@swisspug.org>
Date:   Sun Sep 13 08:08:00 2015 +0200

    Added POLICY to list of COMMENT ON objects.

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 1030738..2133e77 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -43,6 +43,7 @@ COMMENT ON
   OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) |
   OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
   OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
+  POLICY <replaceable class="PARAMETER">policy_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
   ROLE <replaceable class="PARAMETER">object_name</replaceable> |
   RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |

definitions_and_example_for_comment_on_policy.patchapplication/softgrid-patch; name=definitions_and_example_for_comment_on_policy.patchDownload

commit 9f48b64e5220d5e5fa96a2a254219acd3e727072
Author: Charles Clavadetscher <clavadetscher@swisspug.org>
Date:   Sun Sep 13 15:01:55 2015 +0200

    Addition of defintions and an example for COMMENT ON POLICY.

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 2133e77..197f78a 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -115,6 +115,7 @@ COMMENT ON
     <term><replaceable class="parameter">function_name</replaceable></term>
     <term><replaceable class="parameter">operator_name</replaceable></term>
     <term><replaceable class="parameter">rule_name</replaceable></term>
+    <term><replaceable class="parameter">policy_name</replaceable></term>
     <term><replaceable class="parameter">trigger_name</replaceable></term>
     <listitem>
      <para>
@@ -134,9 +135,9 @@ COMMENT ON
     <term><replaceable class="parameter">domain_name</replaceable></term>
     <listitem>
      <para>
-      When creating a comment on a constraint on a table or a domain, these
-      parameters specify the name of the table or domain on which the
-      constraint is defined.
+      When creating a comment on a constraint, a table, a domain or
+      a policy these parameters specify the name of the table or domain on
+      which the constraint is defined.
      </para>
     </listitem>
    </varlistentry>
@@ -316,6 +317,7 @@ COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
+COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 COMMENT ON SCHEMA my_schema IS 'Departmental data';

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Charles Clavadetscher (#6)

1 attachment(s)

Re: [DOCS] Missing COMMENT ON POLICY

Stephen

On 13/09/2015 15:26, Charles Clavadetscher wrote:

Hello Stephen

On 13/09/2015 14:49, Stephen Frost wrote:

Charles,

Just FYI, on these lists, we'd prefer it if you wouldn't top-post.

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Yes, of course. I will take care of that and send a new patch.

Thanks!

Who will then git push it?

I'd be happy to take care of it, though any of the committers may pick
it up, of course. If there's a concern about the patch being missed or
forgotten then it can be added to the commitfest system (here:
http://commitfest.postgresql.org). I don't believe there's a risk of
that here, but you're welcome to add it if you'd like, of course.

Thank you for your feedback.

Thank you for working on this!

Stephen

In the attachement the new patch. I was not able to create one with both
commits so I also added the first one.
I think that documentation should be as complete as possible, but if you
say that there is no risk in missing the update, then I don't see a need
to add a line in the commitfest.

Thank you also for the hint on top-posting. I was not aware of that.
Have a good Sunday.
Charles

I noticed that the position of the parameter "policy_name" in the
description list of parameters was not at the (alphabetically) correct
position. I changed that and the result is attached.

I think/hope that is now all correct.

Thank you and bye
Charles

Attachments:

correct_order_position_of_parameter.patchapplication/softgrid-patch; name=correct_order_position_of_parameter.patchDownload

commit 51ef905d3d81c18634c7bc6d40f02e602cc5af3c
Author: Charles Clavadetscher <clavadetscher@swisspug.org>
Date:   Sun Sep 13 15:50:33 2015 +0200

    Move of parameter description line to correct position.

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 197f78a..3321d4b 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -114,8 +114,8 @@ COMMENT ON
     <term><replaceable class="parameter">constraint_name</replaceable></term>
     <term><replaceable class="parameter">function_name</replaceable></term>
     <term><replaceable class="parameter">operator_name</replaceable></term>
-    <term><replaceable class="parameter">rule_name</replaceable></term>
     <term><replaceable class="parameter">policy_name</replaceable></term>
+    <term><replaceable class="parameter">rule_name</replaceable></term>
     <term><replaceable class="parameter">trigger_name</replaceable></term>
     <listitem>
      <para>

Stephen Frost

sfrost@snowman.net

over 10 years ago

In reply to: Charles Clavadetscher (#7)

Re: [DOCS] Missing COMMENT ON POLICY

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

I noticed that the position of the parameter "policy_name" in the
description list of parameters was not at the (alphabetically)
correct position. I changed that and the result is attached.

Thanks!

I think/hope that is now all correct.

We generally prefer one complete patch which represents the total set
of changes to a lot of individual little patches which build on each
other.

If you're using git and have these patches on a branch as different
commits, you can do an interactive rebase to squash them all together,
like this:

git rebase -i

That will open an editor and then you can choose the action to take for
each patch. Generally, I'll make the first patch 'reword' and the
rest 'squash'. Saving and exiting the editor will then take you to
another editor session where you'll have an opportunity to reword the
commit message (to incorporate all of the changes).

Once all of that's done, you can use 'git format-patch' to create a file
which includes the commit message and the patch. I generally run it
like so:

git format-patch @{u} --stdout > ~/patches/filename-for-patch.patch

Hopefully that helps.

Thanks!

Stephen

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Stephen Frost (#8)

1 attachment(s)

Re: [DOCS] Missing COMMENT ON POLICY

Hi Stephen

On 13/09/2015 16:56, Stephen Frost wrote:

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

I noticed that the position of the parameter "policy_name" in the
description list of parameters was not at the (alphabetically)
correct position. I changed that and the result is attached.

Thanks!

I think/hope that is now all correct.

We generally prefer one complete patch which represents the total set
of changes to a lot of individual little patches which build on each
other.

If you're using git and have these patches on a branch as different
commits, you can do an interactive rebase to squash them all together,
like this:

git rebase -i

That will open an editor and then you can choose the action to take for
each patch. Generally, I'll make the first patch 'reword' and the
rest 'squash'. Saving and exiting the editor will then take you to
another editor session where you'll have an opportunity to reword the
commit message (to incorporate all of the changes).

Once all of that's done, you can use 'git format-patch' to create a file
which includes the commit message and the patch. I generally run it
like so:

git format-patch @{u} --stdout > ~/patches/filename-for-patch.patch

Hopefully that helps.

Yes, that helped a lot! In the attachment now a single patch file with
all changes.

Thank you a lot. BTW, looking forward to the server programming workshop
in Vienna.

Bye
Charles

Attachments:

update_comment_doc_with_policy.patchapplication/softgrid-patch; name=update_comment_doc_with_policy.patchDownload

From e513183a7ed539cd341c62550ac3a6bbaa471c5e Mon Sep 17 00:00:00 2001
From: Charles Clavadetscher <clavadetscher@swisspug.org>
Date: Sun, 13 Sep 2015 11:02:25 +0200
Subject: [PATCH] Addition of POLICY to list of COMMENT objects, parameter
 lists and examples.

Addition of defintions and an example for COMMENT ON POLICY.

Move of parameter description line to correct position.
---
 doc/src/sgml/ref/comment.sgml | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 1030738..3321d4b 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -43,6 +43,7 @@ COMMENT ON
   OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) |
   OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
   OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
+  POLICY <replaceable class="PARAMETER">policy_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
   ROLE <replaceable class="PARAMETER">object_name</replaceable> |
   RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
@@ -113,6 +114,7 @@ COMMENT ON
     <term><replaceable class="parameter">constraint_name</replaceable></term>
     <term><replaceable class="parameter">function_name</replaceable></term>
     <term><replaceable class="parameter">operator_name</replaceable></term>
+    <term><replaceable class="parameter">policy_name</replaceable></term>
     <term><replaceable class="parameter">rule_name</replaceable></term>
     <term><replaceable class="parameter">trigger_name</replaceable></term>
     <listitem>
@@ -133,9 +135,9 @@ COMMENT ON
     <term><replaceable class="parameter">domain_name</replaceable></term>
     <listitem>
      <para>
-      When creating a comment on a constraint on a table or a domain, these
-      parameters specify the name of the table or domain on which the
-      constraint is defined.
+      When creating a comment on a constraint, a table, a domain or
+      a policy these parameters specify the name of the table or domain on
+      which the constraint is defined.
      </para>
     </listitem>
    </varlistentry>
@@ -315,6 +317,7 @@ COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
+COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 COMMENT ON SCHEMA my_schema IS 'Departmental data';
-- 
1.9.1

#10

Stephen Frost

sfrost@snowman.net

over 10 years ago

In reply to: Charles Clavadetscher (#9)

Re: [DOCS] Missing COMMENT ON POLICY

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Yes, that helped a lot! In the attachment now a single patch file
with all changes.

I've pushed this fix now.

Thanks!

Stephen

#11

Charles Clavadetscher

clavadetscher@swisspug.org

over 10 years ago

In reply to: Stephen Frost (#10)

Re: [DOCS] Missing COMMENT ON POLICY

Hi Stephen

On 15.09.2015, at 17:13, Stephen Frost <sfrost@snowman.net> wrote:

Charles,

* Charles Clavadetscher (clavadetscher@swisspug.org) wrote:

Yes, that helped a lot! In the attachment now a single patch file
with all changes.

I've pushed this fix now.

Thanks!

Stephen

Thanks, too
Charles

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers