Thread: Example error in createdb doc

On Thu, Oct 27, 2016 at 09:01:59PM -0400, Jason O'Donnell wrote:
> Hello,
>
> I believe I've found an incorrect example in the createdb documentation:
> https://www.postgresql.org/docs/current/static/app-createdb.html
>
> The example given for createdb fails because template0 is not provided:
>
> [~] createdb -p 5000 -h eden -E LATIN1 -e demo
> CREATE DATABASE demo ENCODING 'LATIN1';
> createdb: database creation failed: ERROR:  new encoding (LATIN1) is
> incompatible with the encoding of the template database (SQL_ASCII)
> HINT:  Use the same encoding as in the template database, or use template0 as
> template.
>
> I've attached a patch that addresses the issue.
...
> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
> index c363bd4..bd1de1f2f 100644
> --- a/doc/src/sgml/ref/createdb.sgml
> +++ b/doc/src/sgml/ref/createdb.sgml
> @@ -366,8 +366,8 @@ PostgreSQL documentation
>      <literal>LATIN1</literal> encoding scheme with a look at the
>      underlying command:
>  <screen>
> -<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
> -<computeroutput>CREATE DATABASE demo ENCODING 'LATIN1';</computeroutput>
> +<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -T template0 -e demo</userinput>
> +<computeroutput>CREATE DATABASE demo ENCODING 'LATIN1' TEMPLATE template0;</computeroutput>
>  </screen></para>
>   </refsect1>

I have looked over this report and patch, and it just doesn't feel
right.  The example is intending to show how to use common psql-like
options to control createdb.  Adding the encoding is nice, but then
having to switch to template0 so the encoding setting works just seems
beyond the scope of what we want do there.

I think the attached patch is more focused.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Bruce Momjian <bruce@momjian.us> writes:
> On Thu, Oct 27, 2016 at 09:01:59PM -0400, Jason O'Donnell wrote:
>> The example given for createdb fails because template0 is not provided:

> I have looked over this report and patch, and it just doesn't feel
> right.  The example is intending to show how to use common psql-like
> options to control createdb.  Adding the encoding is nice, but then
> having to switch to template0 so the encoding setting works just seems
> beyond the scope of what we want do there.

> I think the attached patch is more focused.

I dunno.  The use of -e seems pretty pointless for a call that is going to
yield a trivial CREATE DATABASE command.  Besides, we already showed a
minimal example.  If you think Jason's example is too complex, what about
just subbing in "-T template0" for "-E LATIN1"?  That should work
regardless of other configuration.

Also, your change to the text loses the point that -e provokes printing
the underlying command.  Admittedly, that was somewhat indirect in the way
it was phrased before, but now the concept is just gone entirely; that
doesn't feel like an improvement either.

Personally I thought Jason's patch was fine as-is.

            regards, tom lane

On Tue, Nov 22, 2016 at 06:17:35PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Thu, Oct 27, 2016 at 09:01:59PM -0400, Jason O'Donnell wrote:
> >> The example given for createdb fails because template0 is not provided:
>
> > I have looked over this report and patch, and it just doesn't feel
> > right.  The example is intending to show how to use common psql-like
> > options to control createdb.  Adding the encoding is nice, but then
> > having to switch to template0 so the encoding setting works just seems
> > beyond the scope of what we want do there.
>
> > I think the attached patch is more focused.
>
> I dunno.  The use of -e seems pretty pointless for a call that is going to
> yield a trivial CREATE DATABASE command.  Besides, we already showed a
> minimal example.  If you think Jason's example is too complex, what about
> just subbing in "-T template0" for "-E LATIN1"?  That should work
> regardless of other configuration.

[Just getting back to this November email]

Agreed on using -T.

> Also, your change to the text loses the point that -e provokes printing
> the underlying command.  Admittedly, that was somewhat indirect in the way
> it was phrased before, but now the concept is just gone entirely; that
> doesn't feel like an improvement either.
>
> Personally I thought Jason's patch was fine as-is.

I tried Jason's example on my server and got an error, so I don't want
to trade one error example for another:

    $ createdb -p 5432 -h localhost -E LATIN1 -T template0 -e demo
    CREATE DATABASE demo ENCODING 'LATIN1' TEMPLATE template0;
    createdb: database creation failed: ERROR:  encoding "LATIN1" does not match locale "en_US.UTF-8"
    DETAIL:  The chosen LC_CTYPE setting requires encoding "UTF8".

I went with the template0 example, attached, and applied it to head.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +