Re: nextval parameter is not clear
On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe
wrote:
> On Thu, 2022-11-24 at 15:50 -0500, Kirk Wolak wrote:
> >
> > David, let me see how that looks. From an approach standpoint, I am
> hearing:
> > 1) Keep the example near the definition minimal [just this function]
> > 2) It's okay to create an extra "row" [each function is in a ],
> right after the last function, with a detailed example, like you put below!
>
> The detailed example should not be another row in the table. The table is
> only for
> the description of individual functions. The functions "nextval",
> "setval", "currval"
> and "lastval" each have their own row.
>
> I think the elaborate example should be at the bottom of the page, similar
> to
> the "Examples" section in the reference pages. See for example
> https://www.postgresql.org/docs/current/sql-createstatistics.html
+1
>
> > >
> > > CREATE TABLE seq_example ( id bigint PRIMARY KEY GENERATED BY DEFAULT
> AS IDENTITY ) -- implicit sequence named seq_example_seq is created (or
> whatever is generated...)
> > > INSERT INTO seq_example RETURNING id; -- 1
> > > SELECT currval('seq_example_seq'::regclass); -- 1
>
> I don't think that is a good example to explain sequences to a beginner.
> The sequence behind an identity column is an implementation detail, and
> I wouldn't burden the reader with all that.
>
If you are using these functions it is most commonly in a situation where
serial/identity is involved. I don't see much benefit to having the example
be sanitized to the point of not reflecting realistic usage.
> I think it would be better to create the sequence explicitly and use
> it in the DEFAULT clause of a column definition.
>
I wasn't too happy with that comment when I wrote it either.
I would probably do without the DEFAULT if going the explicit route (but it
isn't a deal breaker).
However, I remembered that we have:
pg_get_serial_sequence ( table text, column text ) → text
I'd be inclined to stay with the GENERATED example but incorporate that
function call into the other examples.
Regardless of the above choice for the example, it seems appropriate for
this page, somewhere, to mention this function and link to its page.
I'd even argue for moving that function definition here.
David J.
Re: nextval parameter is not clear
On Fri, Nov 25, 2022 at 9:58 AM David G. Johnston <
david.g.johns...@gmail.com> wrote:
> On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe
> wrote:
>
>> On Thu, 2022-11-24 at 15:50 -0500, Kirk Wolak wrote:
>> >
>> > David, let me see how that looks. From an approach standpoint, I am
>> hearing:
>> > 1) Keep the example near the definition minimal [just this function]
>> > 2) It's okay to create an extra "row" [each function is in a ],
>> right after the last function, with a detailed example, like you put below!
>>
>> The detailed example should not be another row in the table. The table
>> is only for
>> the description of individual functions. The functions "nextval",
>> "setval", "currval"
>> and "lastval" each have their own row.
>>
>> I think the elaborate example should be at the bottom of the page,
>> similar to
>> the "Examples" section in the reference pages. See for example
>> https://www.postgresql.org/docs/current/sql-createstatistics.html
>
>
> +1
>
>>
>> > >
>> > > CREATE TABLE seq_example ( id bigint PRIMARY KEY GENERATED BY DEFAULT
>> AS IDENTITY ) -- implicit sequence named seq_example_seq is created (or
>> whatever is generated...)
>> > > INSERT INTO seq_example RETURNING id; -- 1
>> > > SELECT currval('seq_example_seq'::regclass); -- 1
>>
>> I don't think that is a good example to explain sequences to a beginner.
>> The sequence behind an identity column is an implementation detail, and
>> I wouldn't burden the reader with all that.
>>
>
> If you are using these functions it is most commonly in a situation where
> serial/identity is involved. I don't see much benefit to having the example
> be sanitized to the point of not reflecting realistic usage.
>
>
>> I think it would be better to create the sequence explicitly and use
>> it in the DEFAULT clause of a column definition.
>>
>
> I wasn't too happy with that comment when I wrote it either.
>
> I would probably do without the DEFAULT if going the explicit route (but
> it isn't a deal breaker).
>
> However, I remembered that we have:
>
> pg_get_serial_sequence ( table text, column text ) → text
>
> I'd be inclined to stay with the GENERATED example but incorporate that
> function call into the other examples.
>
> Regardless of the above choice for the example, it seems appropriate for
> this page, somewhere, to mention this function and link to its page.
>
> I'd even argue for moving that function definition here.
>
> David J.
>
>
David,
Wow, it's hard to clip this email and keep the flow. Apologies.
I love the feedback. I will pull that function (pg_get_serial_sequence) in
here (do I leave it where it is? (probably not))???
And make the other changes. Since I have a "whole" area to put the
sample in, and I did not like the flow of the sample that much.
(I was focused on the make/patch process so I can become useful)... Let me
now craft it up a bit and apply all of this good feedback.
Let me create a better flow... True beginner (CREATE SEQUENCE ...), then
More advanced, like your example, then using this last function,
which qualifies as advanced... relative to someone looking at "nextval", et
al.
Thanks!
Re: temporary file size clarification
On Thu, Nov 24, 2022 at 10:14:20AM +0100, Daniel Gustafsson wrote:
> > On 23 Nov 2022, at 20:43, Bruce Momjian wrote:
> >
> > On Wed, Nov 16, 2022 at 10:26:38AM +, PG Doc comments form wrote:
> >> The following documentation comment has been logged on the website:
> >>
> >> Page: https://www.postgresql.org/docs/14/runtime-config-logging.html
> >> Description:
> >>
> >> The setting log_temp_files will enable logging of the usage of temporary
> >> files, including their size in the log files. The setting is given in
> >> kilobytes, which is clearly documented. However, I could not find any
> >> clear
> >> documentation that describes the unit of size that is used in the logfiles
> >> themselves, the log line is something like "profiles@profiles LOG:
> >> temporary file: path "base/pgsql_tmp/pgsql_tmp31863.1", size 3137536" but
> >> there is no size unit in the logfile or in the settings documentation. Can
> >> you add whether the log line is in bytes/kilobytes/megabytes?
> >
> > Uh, I believe it is simply in bytes.
>
> It is, the relevant code path for the logging is:
>
>if ((size / 1024) >= log_temp_files)
>ereport(LOG,
>(errmsg("temporary file: path \"%s\", size %lu",
>path, (unsigned long) size)));
>
> I don't think it's a bad idea to specify the unit in the documentation though,
> as suggested by the OP. Since the setting considers a value without unit as
> kb, and the logged value is without unit, there is room for confusion.
>
> How about something like the attached?
+1
--
Bruce Momjian https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
Re: nextval parameter is not clear
On Fri, Nov 25, 2022 at 9:58 AM David G. Johnston <
david.g.johns...@gmail.com> wrote:
> On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe
> wrote:
>
>> On Thu, 2022-11-24 at 15:50 -0500, Kirk Wolak wrote:
>> >
>> > David, let me see how that looks. From an approach standpoint, I am
>> hearing:
>>
> I think it would be better to create the sequence explicitly and use
>> it in the DEFAULT clause of a column definition.
>>
>
> I wasn't too happy with that comment when I wrote it either.
>
> I would probably do without the DEFAULT if going the explicit route (but
> it isn't a deal breaker).
>
> However, I remembered that we have:
>
> pg_get_serial_sequence ( table text, column text ) → text
>
> I'd be inclined to stay with the GENERATED example but incorporate that
> function call into the other examples.
>
> Regardless of the above choice for the example, it seems appropriate for
> this page, somewhere, to mention this function and link to its page.
>
> I'd even argue for moving that function definition here.
>
> David J.
>
Okay, I've really reworked the example, and it all tests out.
I took the advice of Laurenz about the separate section outside the table.
I did not move the function, it seemed alphabetical where it was (easy
enough to move), but I did use that function twice!
Break out the RED ink and let me know what you think!
Kirk
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..360cb48f70 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,11 @@ $.* ? (@ like_regex "^\\d+$")
command.
+
+SELECT nextval('myseq'::regclass);
+
+
+
This function requires USAGE
or UPDATE privilege on the sequence.
@@ -17657,11 +17662,11 @@ $.* ? (@ like_regex "^\\d+$")
Furthermore, the value reported by currval is not
changed in this case. For example,
-SELECT setval('myseq', 42); Next
nextval will return 43
-SELECT setval('myseq', 42, true); Same as
above
-SELECT setval('myseq', 42, false);Next
nextval will return 42
+SELECT setval('myseq', 42); -- The next
nextval('myseq') will return 43
+SELECT setval('myseq', 42, true); -- Same as
above
+SELECT setval('myseq', 42, false);-- The next
nextval('myseq') will return 42
-The result returned by setval is just the value
of its
+The result returned by setval is the value of its
second argument.
@@ -17669,7 +17674,6 @@ SELECT setval('myseq', 42, false);
Next nextval
-
@@ -17686,6 +17690,9 @@ SELECT setval('myseq', 42, false);
Next nextvalnextval since
the current session did.
+
+SELECT currval('myseq'::regclass);
+
This function requires USAGE
@@ -17707,19 +17714,75 @@ SELECT setval('myseq', 42, false);
Next nextvalcurrval, except that instead
of taking the sequence name as an argument it refers to whichever
sequence nextval was most recently applied to
-in the current session. It is an error to call
-lastval if nextval
-has not yet been called in the current session.
+in the current session. (An error is reported if
nextval has
+never been called in this session.)
+
+SELECT lastval();
+
This function requires USAGE
or SELECT privilege on the last used sequence.
+
+
+
+
+ Example
+
+CREATE SCHEMA play;-- Create a
play schema
+SET search_path = play;-- Make sure we
create this in the play schema
+
+CREATE SEQUENCE test_seq;
+
+SELECT nextval('test_seq'::regclass); --
1
+SELECT currval('test_seq');--
1
+SELECT lastval(); --
1
+-- If you want to see this sequence in psql
+\ds test_seq
+-- If you want to see all sequences in psql
+\ds
+
+-- Using the DEFAULT value you can assign this SEQUENCE to be
used when the field is not assigned a value
+CREATE TABLE t1 (id bigint NOT NULL DEFAULT nextval('test_seq'), other_data
text); -- links column/sequence
+
+INSERT INTO t1 (other_data) VALUES ('Some Data'); -- Assigns
the next ID automatically
+INSERT INTO t1 (other_data) VALUES ('Some Data')
+ RETURNING id;-- Assigns
the next ID, and returns it to you!
+
+INSERT INTO t1 (id, other_data) VALUES (NULL, 'Some Data');
+-- Oops, you forced the ID to NULL: error violates not-null
constraint
+
+INSERT INTO t1 (id, other_data) VALUES (nextval('test_seq'), 'Some Data')
+ RETURNING id;--
Redundant, but useful in some ETL
+
+-- If you create a table with the GENERATED syntax, a sequence
is generated behind the scenes
+
+CREATE TABLE t2 ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
other_data text);
+
+-- An implicit seque
