Skip to content

Commit 57a548b

Browse files
author
Commitfest Bot
committed
[CF 1608] v20251102 - declarative session variables, LET command
This branch was automatically generated by a robot using patches from an email thread registered at: https://commitfest.postgresql.org/patch/1608 The branch will be overwritten each time a new patch version is posted to the thread, and also periodically to check for bitrot caused by changes on the master branch. Patch(es): https://www.postgresql.org/message-id/CAFj8pRAOTQ5BkKvCFHkUE=HWzirZhVzxE5iugbcOsz=z5R0ogA@mail.gmail.com Author(s): Pavel Stehule
2 parents 1213cb4 + b6408ba commit 57a548b

File tree

117 files changed

+7833
-79
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

117 files changed

+7833
-79
lines changed

‎doc/src/sgml/catalogs.sgml‎

Lines changed: 135 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,11 @@
369369
<entry><link linkend="catalog-pg-user-mapping"><structname>pg_user_mapping</structname></link></entry>
370370
<entry>mappings of users to foreign servers</entry>
371371
</row>
372+
373+
<row>
374+
<entry><link linkend="catalog-pg-variable"><structname>pg_variable</structname></link></entry>
375+
<entry>session variables</entry>
376+
</row>
372377
</tbody>
373378
</tgroup>
374379
</table>
@@ -3358,7 +3363,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
33583363
<literal>f</literal> = function,
33593364
<literal>T</literal> = type,
33603365
<literal>n</literal> = schema,
3361-
<literal>L</literal> = large object
3366+
<literal>L</literal> = large object,
3367+
<literal>V</literal> = session variable
33623368
</para></entry>
33633369
</row>
33643370

@@ -9834,4 +9840,132 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
98349840
</table>
98359841
</sect1>
98369842

9843+
<sect1 id="catalog-pg-variable">
9844+
<title><structname>pg_variable</structname></title>
9845+
9846+
<indexterm zone="catalog-pg-variable">
9847+
<primary>pg_variable</primary>
9848+
</indexterm>
9849+
9850+
<para>
9851+
The catalog <structname>pg_variable</structname> stores information about
9852+
session variables.
9853+
</para>
9854+
9855+
<table>
9856+
<title><structname>pg_variable</structname> Columns</title>
9857+
<tgroup cols="1">
9858+
<thead>
9859+
<row>
9860+
<entry role="catalog_table_entry"><para role="column_definition">
9861+
Column Type
9862+
</para>
9863+
<para>
9864+
Description
9865+
</para></entry>
9866+
</row>
9867+
</thead>
9868+
9869+
<tbody>
9870+
<row>
9871+
<entry role="catalog_table_entry"><para role="column_definition">
9872+
<structfield>oid</structfield> <type>oid</type>
9873+
</para>
9874+
<para>
9875+
Row identifier
9876+
</para></entry>
9877+
</row>
9878+
9879+
<row>
9880+
<entry role="catalog_table_entry"><para role="column_definition">
9881+
<structfield>vartype</structfield> <type>oid</type>
9882+
(references <link linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>)
9883+
</para>
9884+
<para>
9885+
The OID of the variable's data type
9886+
</para></entry>
9887+
</row>
9888+
9889+
<row>
9890+
<entry role="catalog_table_entry"><para role="column_definition">
9891+
<structfield>varcreate_lsn</structfield> <type>pg_lsn</type>
9892+
</para>
9893+
<para>
9894+
LSN of the transaction where the variable was created.
9895+
<structfield>varcreate_lsn</structfield> and
9896+
<structfield>oid</structfield> together form the all-time unique
9897+
identifier (<structfield>oid</structfield> alone is not enough, since
9898+
object identifiers can get reused).
9899+
</para></entry>
9900+
</row>
9901+
9902+
<row>
9903+
<entry role="catalog_table_entry"><para role="column_definition">
9904+
<structfield>varname</structfield> <type>name</type>
9905+
</para>
9906+
<para>
9907+
Name of the session variable
9908+
</para></entry>
9909+
</row>
9910+
9911+
<row>
9912+
<entry role="catalog_table_entry"><para role="column_definition">
9913+
<structfield>varnamespace</structfield> <type>oid</type>
9914+
(references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>oid</structfield>)
9915+
</para>
9916+
<para>
9917+
The OID of the namespace that contains this variable
9918+
</para></entry>
9919+
</row>
9920+
9921+
<row>
9922+
<entry role="catalog_table_entry"><para role="column_definition">
9923+
<structfield>varowner</structfield> <type>oid</type>
9924+
(references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
9925+
</para>
9926+
<para>
9927+
Owner of the variable
9928+
</para></entry>
9929+
</row>
9930+
9931+
<row>
9932+
<entry role="catalog_table_entry"><para role="column_definition">
9933+
<structfield>vartypmod</structfield> <type>int4</type>
9934+
</para>
9935+
<para>
9936+
<structfield>vartypmod</structfield> records type-specific data
9937+
supplied at variable creation time (for example, the maximum
9938+
length of a <type>varchar</type> column). It is passed to
9939+
type-specific input functions and length coercion functions.
9940+
The value will generally be -1 for types that do not need <structfield>vartypmod</structfield>.
9941+
</para></entry>
9942+
</row>
9943+
9944+
<row>
9945+
<entry role="catalog_table_entry"><para role="column_definition">
9946+
<structfield>varcollation</structfield> <type>oid</type>
9947+
(references <link linkend="catalog-pg-collation"><structname>pg_collation</structname></link>.<structfield>oid</structfield>)
9948+
</para>
9949+
<para>
9950+
The defined collation of the variable, or zero if the variable is
9951+
not of a collatable data type.
9952+
</para></entry>
9953+
</row>
9954+
9955+
<row>
9956+
<entry role="catalog_table_entry"><para role="column_definition">
9957+
<structfield>varacl</structfield> <type>aclitem[]</type>
9958+
</para>
9959+
<para>
9960+
Access privileges; see
9961+
<xref linkend="sql-grant"/> and
9962+
<xref linkend="sql-revoke"/>
9963+
for details
9964+
</para></entry>
9965+
</row>
9966+
9967+
</tbody>
9968+
</tgroup>
9969+
</table>
9970+
</sect1>
98379971
</chapter>

‎doc/src/sgml/ddl.sgml‎

Lines changed: 78 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2025,6 +2025,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
20252025
For sequences, this privilege also allows use of the
20262026
<function>currval</function> function.
20272027
For large objects, this privilege allows the object to be read.
2028+
For session variables, this privilege allows the object to be read.
20282029
</para>
20292030
</listitem>
20302031
</varlistentry>
@@ -2060,6 +2061,8 @@ REVOKE ALL ON accounts FROM PUBLIC;
20602061
<function>setval</function> functions.
20612062
For large objects, this privilege allows writing or truncating the
20622063
object.
2064+
For session variables, this privilege allows to set a value to the
2065+
object.
20632066
</para>
20642067
</listitem>
20652068
</varlistentry>
@@ -2304,7 +2307,8 @@ REVOKE ALL ON accounts FROM PUBLIC;
23042307
<literal>LARGE OBJECT</literal>,
23052308
<literal>SEQUENCE</literal>,
23062309
<literal>TABLE</literal> (and table-like objects),
2307-
table column
2310+
table column,
2311+
<literal>SESSION VARIABLE</literal>
23082312
</entry>
23092313
</row>
23102314
<row>
@@ -2319,7 +2323,8 @@ REVOKE ALL ON accounts FROM PUBLIC;
23192323
<literal>LARGE OBJECT</literal>,
23202324
<literal>SEQUENCE</literal>,
23212325
<literal>TABLE</literal>,
2322-
table column
2326+
table column,
2327+
<literal>SESSION VARIABLE</literal>
23232328
</entry>
23242329
</row>
23252330
<row>
@@ -2506,6 +2511,12 @@ REVOKE ALL ON accounts FROM PUBLIC;
25062511
<entry><literal>U</literal></entry>
25072512
<entry><literal>\dT+</literal></entry>
25082513
</row>
2514+
<row>
2515+
<entry><literal>SESSION VARIABLE</literal></entry>
2516+
<entry><literal>rw</literal></entry>
2517+
<entry><literal>none</literal></entry>
2518+
<entry><literal>\dV+</literal></entry>
2519+
</row>
25092520
</tbody>
25102521
</tgroup>
25112522
</table>
@@ -5362,6 +5373,71 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
53625373
</para>
53635374
</sect1>
53645375

5376+
<sect1 id="ddl-session-variables">
5377+
<title>Session Variables</title>
5378+
5379+
<indexterm zone="ddl-session-variables">
5380+
<primary>Session variables</primary>
5381+
</indexterm>
5382+
5383+
<indexterm>
5384+
<primary>session variable</primary>
5385+
</indexterm>
5386+
5387+
<para>
5388+
Session variables are database objects that can hold a value.
5389+
Session variables, like relations, exist within a schema and their access
5390+
is controlled via <command>GRANT</command> and <command>REVOKE</command>
5391+
commands. A session variable can be created by the <command>CREATE
5392+
VARIABLE</command> command.
5393+
</para>
5394+
5395+
<para>
5396+
The session variable holds value in session memory. This value is private
5397+
to each session and is released when the session ends.
5398+
</para>
5399+
5400+
<para>
5401+
In an query the session variable can be used only inside
5402+
<firstterm>variable fence</firstterm>. This is special syntax for
5403+
session variable identifier, and can be used only for session variable
5404+
identifier. The special syntax for accessing session variables removes
5405+
risk of collisions between variable identifiers and column names.
5406+
</para>
5407+
5408+
<para>
5409+
The value of a session variable is set with the SQL statement
5410+
<command>LET</command>. The value of a session variable can be retrieved
5411+
with the SQL statement <command>SELECT</command>.
5412+
<programlisting>
5413+
CREATE VARIABLE var1 AS date;
5414+
LET var1 = current_date;
5415+
SELECT VARIABLE(var1);
5416+
</programlisting>
5417+
5418+
or
5419+
5420+
<programlisting>
5421+
CREATE VARIABLE public.current_user_id AS integer;
5422+
GRANT SELECT ON VARIABLE public.current_user_id TO PUBLIC;
5423+
LET current_user_id = (SELECT id FROM users WHERE usename = session_user);
5424+
SELECT VARIABLE(current_user_id);
5425+
</programlisting>
5426+
</para>
5427+
5428+
<para>
5429+
The value of a session variable is local to the current session. Retrieving
5430+
a variable's value returns a <literal>NULL</literal>, unless its value has
5431+
been set to something else in the current session using the
5432+
<command>LET</command> command. Session variables are not transactional:
5433+
any changes made to the value of a session variable in a transaction won't
5434+
be undone if the transaction is rolled back (just like variables in
5435+
procedural languages). Session variables themselves are persistent, but
5436+
their values are neither persistent nor shared (like the content of
5437+
temporary tables).
5438+
</para>
5439+
</sect1>
5440+
53655441
<sect1 id="ddl-others">
53665442
<title>Other Database Objects</title>
53675443

‎doc/src/sgml/func/func-info.sgml‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -740,6 +740,25 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
740740
</para></entry>
741741
</row>
742742

743+
<row>
744+
<entry role="func_table_entry"><para role="func_signature">
745+
<indexterm>
746+
<primary>has_session_variable_privilege</primary>
747+
</indexterm>
748+
<function>has_session_variable_privilege</function> (
749+
<optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
750+
<parameter>session_variable</parameter> <type>text</type> or <type>oid</type>,
751+
<parameter>privilege</parameter> <type>text</type> )
752+
<returnvalue>boolean</returnvalue>
753+
</para>
754+
<para>
755+
Does user have privilege for session variable?
756+
Allowable privilege types are
757+
<literal>SELECT</literal>, and
758+
<literal>UPDATE</literal>.
759+
</para></entry>
760+
</row>
761+
743762
<row>
744763
<entry role="func_table_entry"><para role="func_signature">
745764
<indexterm>
@@ -1089,8 +1108,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
10891108
't' for <literal>TABLESPACE</literal>,
10901109
'F' for <literal>FOREIGN DATA WRAPPER</literal>,
10911110
'S' for <literal>FOREIGN SERVER</literal>,
1092-
or
1093-
'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
1111+
'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal> or
1112+
'V' for <literal>SESSION VARIABLE</literal>.
10941113
</para></entry>
10951114
</row>
10961115

@@ -1358,6 +1377,19 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
13581377
Is type (or domain) visible in search path?
13591378
</para></entry>
13601379
</row>
1380+
1381+
<row>
1382+
<entry role="func_table_entry"><para role="func_signature">
1383+
<indexterm>
1384+
<primary>pg_variable_is_visible</primary>
1385+
</indexterm>
1386+
<function>pg_variable_is_visible</function> ( <parameter>variable</parameter> <type>oid</type> )
1387+
<returnvalue>boolean</returnvalue>
1388+
</para>
1389+
<para>
1390+
Is session variable visible in search path?
1391+
</para></entry>
1392+
</row>
13611393
</tbody>
13621394
</tgroup>
13631395
</table>

‎doc/src/sgml/glossary.sgml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1711,6 +1711,22 @@
17111711
</glossdef>
17121712
</glossentry>
17131713

1714+
<glossentry id="glossary-session-variable">
1715+
<glossterm>Session variable</glossterm>
1716+
<glossdef>
1717+
<para>
1718+
A persistent database object that holds a value in session memory. This
1719+
value is private to each session and is released when the session ends.
1720+
The default value of the session variable is null. Read or write access
1721+
to session variables is controlled by privileges, similar to other database
1722+
objects.
1723+
</para>
1724+
<para>
1725+
For more information, see <xref linkend="ddl-session-variables"/>.
1726+
</para>
1727+
</glossdef>
1728+
</glossentry>
1729+
17141730
<glossentry id="glossary-shared-memory">
17151731
<glossterm>Shared memory</glossterm>
17161732
<glossdef>

‎doc/src/sgml/parallel.sgml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -515,6 +515,12 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
515515
Plan nodes that reference a correlated <literal>SubPlan</literal>.
516516
</para>
517517
</listitem>
518+
519+
<listitem>
520+
<para>
521+
Plan nodes that use a session variable.
522+
</para>
523+
</listitem>
518524
</itemizedlist>
519525

520526
<sect2 id="parallel-labeling">

‎doc/src/sgml/plpgsql.sgml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6036,6 +6036,20 @@ $$ LANGUAGE plpgsql STRICT IMMUTABLE;
60366036
</programlisting>
60376037
</para>
60386038
</sect3>
6039+
6040+
<sect3 id="plpgsql-porting-package-variables">
6041+
<title><command>Packages and package variables</command></title>
6042+
6043+
<para>
6044+
The <application>PL/pgSQL</application> language has no packages, and
6045+
therefore no package variables or package constants.
6046+
You can consider translating an Oracle package into a schema in
6047+
<productname>PostgreSQL</productname>. Package functions and procedures
6048+
would then become functions and procedures in that schema, and package
6049+
variables could be translated to session variables in that schema.
6050+
(see <xref linkend="ddl-session-variables"/>).
6051+
</para>
6052+
</sect3>
60396053
</sect2>
60406054

60416055
<sect2 id="plpgsql-porting-appendix">

0 commit comments

Comments
 (0)