begriffs open source - ai-pg/blob - full-docs/man7/SET.7

   1 '\" t
   2 .\"     Title: SET
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SET" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SET \- change a run\-time parameter
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 SET [ SESSION | LOCAL ] \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | \*(Aq\fIvalue\fR\*(Aq | DEFAULT }
  36 SET [ SESSION | LOCAL ] TIME ZONE { \fIvalue\fR | \*(Aq\fIvalue\fR\*(Aq | LOCAL | DEFAULT }
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 The
  41 \fBSET\fR
  42 command changes run\-time configuration parameters\&. Many of the run\-time parameters listed in
  43 Chapter\ \&19
  44 can be changed on\-the\-fly with
  45 \fBSET\fR\&. (Some parameters can only be changed by superusers and users who have been granted
  46 SET
  47 privilege on that parameter\&. There are also parameters that cannot be changed after server or session start\&.)
  48 \fBSET\fR
  49 only affects the value used by the current session\&.
  50 .PP
  51 If
  52 \fBSET\fR
  53 (or equivalently
  54 \fBSET SESSION\fR) is issued within a transaction that is later aborted, the effects of the
  55 \fBSET\fR
  56 command disappear when the transaction is rolled back\&. Once the surrounding transaction is committed, the effects will persist until the end of the session, unless overridden by another
  57 \fBSET\fR\&.
  58 .PP
  59 The effects of
  60 \fBSET LOCAL\fR
  61 last only till the end of the current transaction, whether committed or not\&. A special case is
  62 \fBSET\fR
  63 followed by
  64 \fBSET LOCAL\fR
  65 within a single transaction: the
  66 \fBSET LOCAL\fR
  67 value will be seen until the end of the transaction, but afterwards (if the transaction is committed) the
  68 \fBSET\fR
  69 value will take effect\&.
  70 .PP
  71 The effects of
  72 \fBSET\fR
  73 or
  74 \fBSET LOCAL\fR
  75 are also canceled by rolling back to a savepoint that is earlier than the command\&.
  76 .PP
  77 If
  78 \fBSET LOCAL\fR
  79 is used within a function that has a
  80 SET
  81 option for the same variable (see
  82 CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))), the effects of the
  83 \fBSET LOCAL\fR
  84 command disappear at function exit; that is, the value in effect when the function was called is restored anyway\&. This allows
  85 \fBSET LOCAL\fR
  86 to be used for dynamic or repeated changes of a parameter within a function, while still having the convenience of using the
  87 SET
  88 option to save and restore the caller\*(Aqs value\&. However, a regular
  89 \fBSET\fR
  90 command overrides any surrounding function\*(Aqs
  91 SET
  92 option; its effects will persist unless rolled back\&.
  93 .if n \{\
  94 .sp
  95 .\}
  96 .RS 4
  97 .it 1 an-trap
  98 .nr an-no-space-flag 1
  99 .nr an-break-flag 1
 100 .br
 101 .ps +1
 102 \fBNote\fR
 103 .ps -1
 104 .br
 105 .PP
 106 In
 107 PostgreSQL
 108 versions 8\&.0 through 8\&.2, the effects of a
 109 \fBSET LOCAL\fR
 110 would be canceled by releasing an earlier savepoint, or by successful exit from a
 111 PL/pgSQL
 112 exception block\&. This behavior has been changed because it was deemed unintuitive\&.
 113 .sp .5v
 114 .RE
 115 .SH "PARAMETERS"
 116 .PP
 117 SESSION
 118 .RS 4
 119 Specifies that the command takes effect for the current session\&. (This is the default if neither
 120 SESSION
 121 nor
 122 LOCAL
 123 appears\&.)
 124 .RE
 125 .PP
 126 LOCAL
 127 .RS 4
 128 Specifies that the command takes effect for only the current transaction\&. After
 129 \fBCOMMIT\fR
 130 or
 131 \fBROLLBACK\fR, the session\-level setting takes effect again\&. Issuing this outside of a transaction block emits a warning and otherwise has no effect\&.
 132 .RE
 133 .PP
 134 \fIconfiguration_parameter\fR
 135 .RS 4
 136 Name of a settable run\-time parameter\&. Available parameters are documented in
 137 Chapter\ \&19
 138 and below\&.
 139 .RE
 140 .PP
 141 \fIvalue\fR
 142 .RS 4
 143 New value of parameter\&. Values can be specified as string constants, identifiers, numbers, or comma\-separated lists of these, as appropriate for the particular parameter\&.
 144 DEFAULT
 145 can be written to specify resetting the parameter to its default value (that is, whatever value it would have had if no
 146 \fBSET\fR
 147 had been executed in the current session)\&.
 148 .RE
 149 .PP
 150 Besides the configuration parameters documented in
 151 Chapter\ \&19, there are a few that can only be adjusted using the
 152 \fBSET\fR
 153 command or that have a special syntax:
 154 .PP
 155 SCHEMA
 156 .RS 4
 157 SET SCHEMA \*(Aq\fIvalue\fR\*(Aq
 158 is an alias for
 159 SET search_path TO \fIvalue\fR\&. Only one schema can be specified using this syntax\&.
 160 .RE
 161 .PP
 162 NAMES
 163 .RS 4
 164 SET NAMES \*(Aq\fIvalue\fR\*(Aq
 165 is an alias for
 166 SET client_encoding TO \fIvalue\fR\&.
 167 .RE
 168 .PP
 169 SEED
 170 .RS 4
 171 Sets the internal seed for the random number generator (the function
 172 \fBrandom\fR)\&. Allowed values are floating\-point numbers between \-1 and 1 inclusive\&.
 173 .sp
 174 The seed can also be set by invoking the function
 175 \fBsetseed\fR:
 176 .sp
 177 .if n \{\
 178 .RS 4
 179 .\}
 180 .nf
 181 SELECT setseed(\fIvalue\fR);
 182 .fi
 183 .if n \{\
 184 .RE
 185 .\}
 186 .RE
 187 .PP
 188 TIME ZONE
 189 .RS 4
 190 SET TIME ZONE \*(Aq\fIvalue\fR\*(Aq
 191 is an alias for
 192 SET timezone TO \*(Aq\fIvalue\fR\*(Aq\&. The syntax
 193 SET TIME ZONE
 194 allows special syntax for the time zone specification\&. Here are examples of valid values:
 195 .PP
 196 \*(AqAmerica/Los_Angeles\*(Aq
 197 .RS 4
 198 The time zone for Berkeley, California\&.
 199 .RE
 200 .PP
 201 \*(AqEurope/Rome\*(Aq
 202 .RS 4
 203 The time zone for Italy\&.
 204 .RE
 205 .PP
 206 \-7
 207 .RS 4
 208 The time zone 7 hours west from UTC (equivalent to PDT)\&. Positive values are east from UTC\&.
 209 .RE
 210 .PP
 211 INTERVAL \*(Aq\-08:00\*(Aq HOUR TO MINUTE
 212 .RS 4
 213 The time zone 8 hours west from UTC (equivalent to PST)\&.
 214 .RE
 215 .PP
 216 LOCAL
 217 .br
 218 DEFAULT
 219 .RS 4
 220 Set the time zone to your local time zone (that is, the server\*(Aqs default value of
 221 \fItimezone\fR)\&.
 222 .RE
 223 .sp
 224 Timezone settings given as numbers or intervals are internally translated to POSIX timezone syntax\&. For example, after
 225 SET TIME ZONE \-7,
 226 \fBSHOW TIME ZONE\fR
 227 would report
 228 <\-07>+07\&.
 229 .sp
 230 Time zone abbreviations are not supported by
 231 \fBSET\fR; see
 232 Section\ \&8.5.3
 233 for more information about time zones\&.
 234 .RE
 235 .SH "NOTES"
 236 .PP
 237 The function
 238 \fBset_config\fR
 239 provides equivalent functionality; see
 240 Section\ \&9.28.1\&. Also, it is possible to UPDATE the
 241 pg_settings
 242 system view to perform the equivalent of
 243 \fBSET\fR\&.
 244 .SH "EXAMPLES"
 245 .PP
 246 Set the schema search path:
 247 .sp
 248 .if n \{\
 249 .RS 4
 250 .\}
 251 .nf
 252 SET search_path TO my_schema, public;
 253 .fi
 254 .if n \{\
 255 .RE
 256 .\}
 257 .PP
 258 Set the style of date to traditional
 259 POSTGRES
 260 with
 261 \(lqday before month\(rq
 262 input convention:
 263 .sp
 264 .if n \{\
 265 .RS 4
 266 .\}
 267 .nf
 268 SET datestyle TO postgres, dmy;
 269 .fi
 270 .if n \{\
 271 .RE
 272 .\}
 273 .PP
 274 Set the time zone for Berkeley, California:
 275 .sp
 276 .if n \{\
 277 .RS 4
 278 .\}
 279 .nf
 280 SET TIME ZONE \*(AqAmerica/Los_Angeles\*(Aq;
 281 .fi
 282 .if n \{\
 283 .RE
 284 .\}
 285 .PP
 286 Set the time zone for Italy:
 287 .sp
 288 .if n \{\
 289 .RS 4
 290 .\}
 291 .nf
 292 SET TIME ZONE \*(AqEurope/Rome\*(Aq;
 293 .fi
 294 .if n \{\
 295 .RE
 296 .\}
 297 .SH "COMPATIBILITY"
 298 .PP
 299 SET TIME ZONE
 300 extends syntax defined in the SQL standard\&. The standard allows only numeric time zone offsets while
 301 PostgreSQL
 302 allows more flexible time\-zone specifications\&. All other
 303 SET
 304 features are
 305 PostgreSQL
 306 extensions\&.
 307 .SH "SEE ALSO"
 308 \fBRESET\fR(7), \fBSHOW\fR(7)