Horton

Thread

Commits

  1. Document deprecated createuser option.

  2. Rename some createuser options.

  3. doc: improve description of adding roles as members

  4. Mark options as deprecated in usage output

  1. createuser --memeber and PG 16

    Bruce Momjian <bruce@momjian.us> — 2023-05-10T17:33:26Z

    In writing the PG 16 release notes, I came upon an oddity in our new
createuser syntax, specifically --role and --member.  It turns out that
--role matches CREATE ROLE ... ROLE IN (and has prior to PG 16) while
the new --member option matches CREATE ROLE ... ROLE.  The PG 16 feature
discussion thread is here:

	https://www.postgresql.org/message-id/flat/69a9851035cf0f0477bcc5d742b031a3%40oss.nttdata.com

This seems like it will be forever confusing to people.  I frankly don't
know why --role matching CREATE ROLE ... ROLE IN was not already
confusing in pre-PG 16.  Any new ideas for improvement?

At a minium I would like to apply the attached doc patch to PG 16 to
improve awkward wording in CREATE ROLE and createuser.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Embrace your flaws.  They make you human, rather than perfect,
  which you will never be.

  2. Re: createuser --memeber and PG 16

    Daniel Gustafsson <daniel@yesql.se> — 2023-05-11T12:21:22Z

    > On 10 May 2023, at 19:33, Bruce Momjian <bruce@momjian.us> wrote:

> I frankly don't
> know why --role matching CREATE ROLE ... ROLE IN was not already
> confusing in pre-PG 16.  Any new ideas for improvement?

IIRC there were a number of ideas presented in that thread but backwards
compatibility with --role already "taken" made it complicated, so --role and
--member were the least bad options.

> At a minium I would like to apply the attached doc patch to PG 16 to
> improve awkward wording in CREATE ROLE and createuser.

No objection.

+        role.  (This in effect makes the new role a <quote>group</quote>.)
While not introduced here, isn't the latter part interesting enough to warrant
not being inside parenthesis?

--
Daniel Gustafsson

  3. Re: createuser --memeber and PG 16

    Bruce Momjian <bruce@momjian.us> — 2023-05-11T13:34:42Z

    On Thu, May 11, 2023 at 02:21:22PM +0200, Daniel Gustafsson wrote:
> > On 10 May 2023, at 19:33, Bruce Momjian <bruce@momjian.us> wrote:
> 
> > I frankly don't
> > know why --role matching CREATE ROLE ... ROLE IN was not already
> > confusing in pre-PG 16.  Any new ideas for improvement?
> 
> IIRC there were a number of ideas presented in that thread but backwards
> compatibility with --role already "taken" made it complicated, so --role and
> --member were the least bad options.
> 
> > At a minimum I would like to apply the attached doc patch to PG 16 to
> > improve awkward wording in CREATE ROLE and createuser.
> 
> No objection.
> 
> +        role.  (This in effect makes the new role a <quote>group</quote>.)
> While not introduced here, isn't the latter part interesting enough to warrant
> not being inside parenthesis?

The concept of group itself is deprecated, which I think is why the
parenthesis are used.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Embrace your flaws.  They make you human, rather than perfect,
  which you will never be.

  4. Re: createuser --memeber and PG 16

    Robert Haas <robertmhaas@gmail.com> — 2023-05-11T14:07:23Z

    On Wed, May 10, 2023 at 1:33 PM Bruce Momjian <bruce@momjian.us> wrote:
> This seems like it will be forever confusing to people.  I frankly don't
> know why --role matching CREATE ROLE ... ROLE IN was not already
> confusing in pre-PG 16.  Any new ideas for improvement?

Yeah, it's a bad situation. I think --role is basically misnamed.
Something like --add-to-group would have been clearer, but that also
has the problem of being inconsistent with the SQL command. The whole
ROLE vs. IN ROLE thing is inherently quite confusing, I think. It's
very easy to get confused about which direction the membership arrows
are pointing.

-- 
Robert Haas
EDB: http://www.enterprisedb.com

  5. Re: createuser --memeber and PG 16

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-05-12T14:35:34Z

    On 11.05.23 16:07, Robert Haas wrote:
> On Wed, May 10, 2023 at 1:33 PM Bruce Momjian <bruce@momjian.us> wrote:
>> This seems like it will be forever confusing to people.  I frankly don't
>> know why --role matching CREATE ROLE ... ROLE IN was not already
>> confusing in pre-PG 16.  Any new ideas for improvement?
> 
> Yeah, it's a bad situation. I think --role is basically misnamed.
> Something like --add-to-group would have been clearer, but that also
> has the problem of being inconsistent with the SQL command. The whole
> ROLE vs. IN ROLE thing is inherently quite confusing, I think. It's
> very easy to get confused about which direction the membership arrows
> are pointing.

It's hard to tell that for the --member option as well.  For

createuser foo --member bar

it's not intuitive whether foo becomes a member of bar or bar becomes a 
member of foo.  Maybe something more verbose like --member-of would help?

  6. Re: createuser --memeber and PG 16

    Michael Paquier <michael@paquier.xyz> — 2023-05-15T07:27:04Z

    On Fri, May 12, 2023 at 04:35:34PM +0200, Peter Eisentraut wrote:
> it's not intuitive whether foo becomes a member of bar or bar becomes a
> member of foo.  Maybe something more verbose like --member-of would help?

Indeed, presented like that it could be confusing, and --member-of
sounds like it could be a good idea instead of --member.
--
Michael

  7. Re: createuser --memeber and PG 16

    Michael Paquier <michael@paquier.xyz> — 2023-05-15T07:33:27Z

    On Thu, May 11, 2023 at 09:34:42AM -0400, Bruce Momjian wrote:
> On Thu, May 11, 2023 at 02:21:22PM +0200, Daniel Gustafsson wrote:
>> IIRC there were a number of ideas presented in that thread but backwards
>> compatibility with --role already "taken" made it complicated, so --role and
>> --member were the least bad options.
>> 
>>> At a minimum I would like to apply the attached doc patch to PG 16 to
>>> improve awkward wording in CREATE ROLE and createuser.
>> 
>> No objection.

None from here as well.

>> +        role.  (This in effect makes the new role a <quote>group</quote>.)
>> While not introduced here, isn't the latter part interesting enough to warrant
>> not being inside parenthesis?
> 
> The concept of group itself is deprecated, which I think is why the
> parenthesis are used.

Not sure on this one.  The original docs come from 58d214e, and this
sentence was already in there.
--
Michael

  8. Re: createuser --memeber and PG 16

    Bruce Momjian <bruce@momjian.us> — 2023-05-15T13:55:45Z

    On Mon, May 15, 2023 at 04:33:27PM +0900, Michael Paquier wrote:
> On Thu, May 11, 2023 at 09:34:42AM -0400, Bruce Momjian wrote:
> > On Thu, May 11, 2023 at 02:21:22PM +0200, Daniel Gustafsson wrote:
> >> IIRC there were a number of ideas presented in that thread but backwards
> >> compatibility with --role already "taken" made it complicated, so --role and
> >> --member were the least bad options.
> >> 
> >>> At a minimum I would like to apply the attached doc patch to PG 16 to
> >>> improve awkward wording in CREATE ROLE and createuser.
> >> 
> >> No objection.
> 
> None from here as well.
> 
> >> +        role.  (This in effect makes the new role a <quote>group</quote>.)
> >> While not introduced here, isn't the latter part interesting enough to warrant
> >> not being inside parenthesis?
> > 
> > The concept of group itself is deprecated, which I think is why the
> > parenthesis are used.
> 
> Not sure on this one.  The original docs come from 58d214e, and this
> sentence was already in there.

True.  I have removed the parenthesis in this updated patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Embrace your flaws.  They make you human, rather than perfect,
  which you will never be.

  9. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-15T20:11:49Z

    On Mon, May 15, 2023 at 04:27:04PM +0900, Michael Paquier wrote:
> On Fri, May 12, 2023 at 04:35:34PM +0200, Peter Eisentraut wrote:
>> it's not intuitive whether foo becomes a member of bar or bar becomes a
>> member of foo.  Maybe something more verbose like --member-of would help?
> 
> Indeed, presented like that it could be confusing, and --member-of
> sounds like it could be a good idea instead of --member.

--member specifieѕ an existing role that will be given membership to the
new role (i.e., GRANT newrole TO existingrole).  IMO --member-of sounds
like the new role will be given membership to the specified existing role
(i.e., GRANT existingrole TO newrole).  IOW a command like

	createuser newrole --member-of existingrole

would make existingrole a "member of" newrole according to \du.  Perhaps
--role should be --member-of because it makes the new role a member of the
existing role.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  10. Re: createuser --memeber and PG 16

    Bruce Momjian <bruce@momjian.us> — 2023-05-19T02:22:32Z

    On Wed, May 10, 2023 at 01:33:26PM -0400, Bruce Momjian wrote:
> In writing the PG 16 release notes, I came upon an oddity in our new
> createuser syntax, specifically --role and --member.  It turns out that
> --role matches CREATE ROLE ... ROLE IN (and has prior to PG 16) while
> the new --member option matches CREATE ROLE ... ROLE.  The PG 16 feature
> discussion thread is here:
> 
> 	https://www.postgresql.org/message-id/flat/69a9851035cf0f0477bcc5d742b031a3%40oss.nttdata.com
> 
> This seems like it will be forever confusing to people.  I frankly don't
> know why --role matching CREATE ROLE ... ROLE IN was not already
> confusing in pre-PG 16.  Any new ideas for improvement?
> 
> At a minium I would like to apply the attached doc patch to PG 16 to
> improve awkward wording in CREATE ROLE and createuser.

Patch applied.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

  11. Re: createuser --memeber and PG 16

    Michael Paquier <michael@paquier.xyz> — 2023-05-19T05:50:31Z

    On Thu, May 18, 2023 at 10:22:32PM -0400, Bruce Momjian wrote:
> Patch applied.

Thanks, Bruce.
--
Michael

  12. Re: createuser --memeber and PG 16

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-05-21T06:00:15Z

    On 15.05.23 22:11, Nathan Bossart wrote:
> On Mon, May 15, 2023 at 04:27:04PM +0900, Michael Paquier wrote:
>> On Fri, May 12, 2023 at 04:35:34PM +0200, Peter Eisentraut wrote:
>>> it's not intuitive whether foo becomes a member of bar or bar becomes a
>>> member of foo.  Maybe something more verbose like --member-of would help?
>>
>> Indeed, presented like that it could be confusing, and --member-of
>> sounds like it could be a good idea instead of --member.
> 
> --member specifieѕ an existing role that will be given membership to the
> new role (i.e., GRANT newrole TO existingrole).  IMO --member-of sounds
> like the new role will be given membership to the specified existing role
> (i.e., GRANT existingrole TO newrole).  IOW a command like
> 
> 	createuser newrole --member-of existingrole
> 
> would make existingrole a "member of" newrole according to \du.  Perhaps
> --role should be --member-of because it makes the new role a member of the
> existing role.

Yeah, that's exactly my confusion.

Maybe

createuser --with-members

and

createuser --member-of

would be clearer.

  13. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-21T14:44:49Z

    On Sun, May 21, 2023 at 08:00:15AM +0200, Peter Eisentraut wrote:
> Maybe
> 
> createuser --with-members
> 
> and
> 
> createuser --member-of
> 
> would be clearer.

Those seem like reasonable choices to me.  I suspect we'll want to keep
--role around for backward compatibility.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  14. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-21T15:22:05Z

    On Sun, May 21, 2023 at 07:44:49AM -0700, Nathan Bossart wrote:
> On Sun, May 21, 2023 at 08:00:15AM +0200, Peter Eisentraut wrote:
>> Maybe
>> 
>> createuser --with-members
>> 
>> and
>> 
>> createuser --member-of
>> 
>> would be clearer.
> 
> Those seem like reasonable choices to me.  I suspect we'll want to keep
> --role around for backward compatibility.

I've attached a draft patch for this.  I also changed --admin to
--with-admin.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  15. Re: createuser --memeber and PG 16

    Bruce Momjian <bruce@momjian.us> — 2023-05-21T15:34:00Z

    On Sun, May 21, 2023 at 08:22:05AM -0700, Nathan Bossart wrote:
> On Sun, May 21, 2023 at 07:44:49AM -0700, Nathan Bossart wrote:
> > On Sun, May 21, 2023 at 08:00:15AM +0200, Peter Eisentraut wrote:
> >> Maybe
> >> 
> >> createuser --with-members
> >> 
> >> and
> >> 
> >> createuser --member-of
> >> 
> >> would be clearer.
> > 
> > Those seem like reasonable choices to me.  I suspect we'll want to keep
> > --role around for backward compatibility.
> 
> I've attached a draft patch for this.  I also changed --admin to
> --with-admin.

If we want to go forward with this, the big question is whether we want
to get this in before beta1.  FYI, the release notes don't mention the
option names.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

  16. Re: createuser --memeber and PG 16

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-05-21T15:45:24Z

    Bruce Momjian <bruce@momjian.us> writes:
> On Sun, May 21, 2023 at 08:22:05AM -0700, Nathan Bossart wrote:
>> I've attached a draft patch for this.  I also changed --admin to
>> --with-admin.

> If we want to go forward with this, the big question is whether we want
> to get this in before beta1.  FYI, the release notes don't mention the
> option names.

+1 for doing it before beta1.

A few comments on the patch:

>>          Indicates an existing role that will be automatically added as a member of the new

"Specifies" would be clearer than "indicates" (not your fault, but
let's avoid the passive construction while we are here).  Likewise
nearby.

>> +		{"member-of", required_argument, NULL, 6},

Why didn't you just translate this as 'g' instead of inventing
a new switch case?

>> -	printf(_("  -a, --admin=ROLE          this role will be a member of new role with admin\n"
>> +	printf(_("  -a, --with-admin=ROLE     this role will be a member of new role with admin\n"

I think clearer would be

>> +	printf(_("  -a, --with-admin=ROLE     ROLE will be a member of new role with admin\n"

Likewise

>> +	printf(_("  -g, --member-of=ROLE      new role will be a member of ROLE\n"));

(I assume that's what this should say, it's backwards ATM)
and

>> +	printf(_("  -m, --with-member=ROLE    ROLE will be a member of new role\n"));

			regards, tom lane

  17. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-21T17:07:56Z

    On Sun, May 21, 2023 at 11:45:24AM -0400, Tom Lane wrote:
> A few comments on the patch:

Thanks for taking a look.

>>>          Indicates an existing role that will be automatically added as a member of the new
> 
> "Specifies" would be clearer than "indicates" (not your fault, but
> let's avoid the passive construction while we are here).  Likewise
> nearby.

Fixed.

>>> +		{"member-of", required_argument, NULL, 6},
> 
> Why didn't you just translate this as 'g' instead of inventing
> a new switch case?

Fixed.  *facepalm*

> I think clearer would be
> 
>>> +	printf(_("  -a, --with-admin=ROLE     ROLE will be a member of new role with admin\n"
> 
> Likewise
> 
>>> +	printf(_("  -g, --member-of=ROLE      new role will be a member of ROLE\n"));
> 
> (I assume that's what this should say, it's backwards ATM)
> and
> 
>>> +	printf(_("  -m, --with-member=ROLE    ROLE will be a member of new role\n"));

Fixed.

How do folks feel about keeping --role undocumented?  Should we give it a
mention in the docs for --member-of?

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  18. Re: createuser --memeber and PG 16

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-05-21T17:20:01Z

    Nathan Bossart <nathandbossart@gmail.com> writes:
> Fixed.

v2 looks good to me, except the documentation wording for --with-role
is needlessly inconsistent with --with-admin.  The --with-admin
wording looks better, so I suggest

-        Indicates the specified existing role should be automatically
+        Specifies an existing role that will be automatically
         added as a member of the new role. Multiple existing roles can

> How do folks feel about keeping --role undocumented?  Should we give it a
> mention in the docs for --member-of?

I'm okay with leaving it undocumented, but I won't fight about it
if somebody wants to argue for the other.

			regards, tom lane

  19. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-21T19:16:58Z

    On Sun, May 21, 2023 at 01:20:01PM -0400, Tom Lane wrote:
> Nathan Bossart <nathandbossart@gmail.com> writes:
>> Fixed.
> 
> v2 looks good to me, except the documentation wording for --with-role
> is needlessly inconsistent with --with-admin.  The --with-admin
> wording looks better, so I suggest
> 
> -        Indicates the specified existing role should be automatically
> +        Specifies an existing role that will be automatically
>          added as a member of the new role. Multiple existing roles can

Will do.

>> How do folks feel about keeping --role undocumented?  Should we give it a
>> mention in the docs for --member-of?
> 
> I'm okay with leaving it undocumented, but I won't fight about it
> if somebody wants to argue for the other.

Alright.  Barring any additional feedback, I'll commit this tonight.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  20. Re: createuser --memeber and PG 16

    Michael Paquier <michael@paquier.xyz> — 2023-05-22T00:11:18Z

    On Sun, May 21, 2023 at 12:16:58PM -0700, Nathan Bossart wrote:
> On Sun, May 21, 2023 at 01:20:01PM -0400, Tom Lane wrote:
> > Nathan Bossart <nathandbossart@gmail.com> writes:
>>> How do folks feel about keeping --role undocumented?  Should we give it a
>>> mention in the docs for --member-of?
>> 
>> I'm okay with leaving it undocumented, but I won't fight about it
>> if somebody wants to argue for the other.
> 
> Alright.  Barring any additional feedback, I'll commit this tonight.

v2 passes the eye test, and I am not spotting any references to the
past option names.  Thanks!

+$node->issues_sql_like(
+   [ 'createuser', 'regress_user11', '--role', 'regress_user1' ],
+   qr/statement: CREATE ROLE regress_user11 NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN NOREPLICATION NOBYPASSRLS IN ROLE regress_user1;/,
+   '--role (for backward compatibility)');

Not sure I would have kept this test, still that's cheap enough to
test.
--
Michael

  21. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-22T03:18:29Z

    On Mon, May 22, 2023 at 09:11:18AM +0900, Michael Paquier wrote:
> On Sun, May 21, 2023 at 12:16:58PM -0700, Nathan Bossart wrote:
>> Alright.  Barring any additional feedback, I'll commit this tonight.
> 
> v2 passes the eye test, and I am not spotting any references to the
> past option names.  Thanks!

Committed.  Thanks for taking a look.  I'll keep an eye on the buildfarm
for a few.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  22. Re: createuser --memeber and PG 16

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-05-22T06:42:28Z

    On 21.05.23 19:07, Nathan Bossart wrote:
> How do folks feel about keeping --role undocumented?  Should we give it a
> mention in the docs for --member-of?

We made a point in this release to document deprecated options 
consistently.  See commit 2f80c95740.

  23. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-22T12:11:14Z

    On Mon, May 22, 2023 at 08:42:28AM +0200, Peter Eisentraut wrote:
> On 21.05.23 19:07, Nathan Bossart wrote:
>> How do folks feel about keeping --role undocumented?  Should we give it a
>> mention in the docs for --member-of?
> 
> We made a point in this release to document deprecated options consistently.
> See commit 2f80c95740.

Alright.  Does the attached patch suffice?

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

  24. Re: createuser --memeber and PG 16

    Michael Paquier <michael@paquier.xyz> — 2023-05-22T22:50:36Z

    On Mon, May 22, 2023 at 05:11:14AM -0700, Nathan Bossart wrote:
> On Mon, May 22, 2023 at 08:42:28AM +0200, Peter Eisentraut wrote:
> > On 21.05.23 19:07, Nathan Bossart wrote:
> >> How do folks feel about keeping --role undocumented?  Should we give it a
> >> mention in the docs for --member-of?
> > 
> > We made a point in this release to document deprecated options consistently.
> > See commit 2f80c95740.
> 
> Alright.  Does the attached patch suffice?

Seeing the precedent with --no-blobs and --blobs, yes, that should be
enough.  You may want to wait until beta1 is stamped to apply
something, though, as the period between the stamp and the tag is used
to check the state of the tarballs to-be-released.
--
Michael

  25. Re: createuser --memeber and PG 16

    Nathan Bossart <nathandbossart@gmail.com> — 2023-05-24T02:39:24Z

    On Tue, May 23, 2023 at 07:50:36AM +0900, Michael Paquier wrote:
> Seeing the precedent with --no-blobs and --blobs, yes, that should be
> enough.  You may want to wait until beta1 is stamped to apply
> something, though, as the period between the stamp and the tag is used
> to check the state of the tarballs to-be-released.

Thanks, committed.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com