begriffs open source - ai-pg/blob - full-docs/src/sgml/man7/CREATE_DATABASE.7

   1 '\" t
   2 .\"     Title: CREATE DATABASE
   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 "CREATE DATABASE" "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 CREATE_DATABASE \- create a new database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE DATABASE \fIname\fR
  36     [ WITH ] [ OWNER [=] \fIuser_name\fR ]
  37            [ TEMPLATE [=] \fItemplate\fR ]
  38            [ ENCODING [=] \fIencoding\fR ]
  39            [ STRATEGY [=] \fIstrategy\fR ]
  40            [ LOCALE [=] \fIlocale\fR ]
  41            [ LC_COLLATE [=] \fIlc_collate\fR ]
  42            [ LC_CTYPE [=] \fIlc_ctype\fR ]
  43            [ BUILTIN_LOCALE [=] \fIbuiltin_locale\fR ]
  44            [ ICU_LOCALE [=] \fIicu_locale\fR ]
  45            [ ICU_RULES [=] \fIicu_rules\fR ]
  46            [ LOCALE_PROVIDER [=] \fIlocale_provider\fR ]
  47            [ COLLATION_VERSION = \fIcollation_version\fR ]
  48            [ TABLESPACE [=] \fItablespace_name\fR ]
  49            [ ALLOW_CONNECTIONS [=] \fIallowconn\fR ]
  50            [ CONNECTION LIMIT [=] \fIconnlimit\fR ]
  51            [ IS_TEMPLATE [=] \fIistemplate\fR ]
  52            [ OID [=] \fIoid\fR ]
  53 .fi
  54 .SH "DESCRIPTION"
  55 .PP
  56 \fBCREATE DATABASE\fR
  57 creates a new
  58 PostgreSQL
  59 database\&.
  60 .PP
  61 To create a database, you must be a superuser or have the special
  62 CREATEDB
  63 privilege\&. See
  64 CREATE ROLE (\fBCREATE_ROLE\fR(7))\&.
  65 .PP
  66 By default, the new database will be created by cloning the standard system database
  67 template1\&. A different template can be specified by writing
  68 TEMPLATE \fIname\fR\&. In particular, by writing
  69 TEMPLATE template0, you can create a pristine database (one where no user\-defined objects exist and where the system objects have not been altered) containing only the standard objects predefined by your version of
  70 PostgreSQL\&. This is useful if you wish to avoid copying any installation\-local objects that might have been added to
  71 template1\&.
  72 .SH "PARAMETERS"
  73 .PP
  74 \fIname\fR
  75 .RS 4
  76 The name of a database to create\&.
  77 .RE
  78 .PP
  79 \fIuser_name\fR
  80 .RS 4
  81 The role name of the user who will own the new database, or
  82 DEFAULT
  83 to use the default (namely, the user executing the command)\&. To create a database owned by another role, you must be able to
  84 SET ROLE
  85 to that role\&.
  86 .RE
  87 .PP
  88 \fItemplate\fR
  89 .RS 4
  90 The name of the template from which to create the new database, or
  91 DEFAULT
  92 to use the default template (template1)\&.
  93 .RE
  94 .PP
  95 \fIencoding\fR
  96 .RS 4
  97 Character set encoding to use in the new database\&. Specify a string constant (e\&.g\&.,
  98 \*(AqSQL_ASCII\*(Aq), or an integer encoding number, or
  99 DEFAULT
 100 to use the default encoding (namely, the encoding of the template database)\&. The character sets supported by the
 101 PostgreSQL
 102 server are described in
 103 Section\ \&23.3.1\&. See below for additional restrictions\&.
 104 .RE
 105 .PP
 106 \fIstrategy\fR
 107 .RS 4
 108 Strategy to be used in creating the new database\&. If the
 109 WAL_LOG
 110 strategy is used, the database will be copied block by block and each block will be separately written to the write\-ahead log\&. This is the most efficient strategy in cases where the template database is small, and therefore it is the default\&. The older
 111 FILE_COPY
 112 strategy is also available\&. This strategy writes a small record to the write\-ahead log for each tablespace used by the target database\&. Each such record represents copying an entire directory to a new location at the filesystem level\&. While this does reduce the write\-ahead log volume substantially, especially if the template database is large, it also forces the system to perform a checkpoint both before and after the creation of the new database\&. In some situations, this may have a noticeable negative impact on overall system performance\&. The
 113 FILE_COPY
 114 strategy is affected by the
 115 file_copy_method
 116 setting\&.
 117 .RE
 118 .PP
 119 \fIlocale\fR
 120 .RS 4
 121 Sets the default collation order and character classification in the new database\&. Collation affects the sort order applied to strings, e\&.g\&., in queries with
 122 ORDER BY, as well as the order used in indexes on text columns\&. Character classification affects the categorization of characters, e\&.g\&., lower, upper, and digit\&. Also sets the associated aspects of the operating system environment,
 123 LC_COLLATE
 124 and
 125 LC_CTYPE\&. The default is the same setting as the template database\&. See
 126 Section\ \&23.2.2.3.1
 127 and
 128 Section\ \&23.2.2.3.2
 129 for details\&.
 130 .sp
 131 Can be overridden by setting
 132 \fIlc_collate\fR,
 133 \fIlc_ctype\fR,
 134 \fIbuiltin_locale\fR, or
 135 \fIicu_locale\fR
 136 individually\&.
 137 .sp
 138 If
 139 \fIlocale_provider\fR
 140 is
 141 builtin, then
 142 \fIlocale\fR
 143 or
 144 \fIbuiltin_locale\fR
 145 must be specified and set to either
 146 C,
 147 C\&.UTF\-8, or
 148 PG_UNICODE_FAST\&.
 149 .if n \{\
 150 .sp
 151 .\}
 152 .RS 4
 153 .it 1 an-trap
 154 .nr an-no-space-flag 1
 155 .nr an-break-flag 1
 156 .br
 157 .ps +1
 158 \fBTip\fR
 159 .ps -1
 160 .br
 161 The other locale settings
 162 lc_messages,
 163 lc_monetary,
 164 lc_numeric, and
 165 lc_time
 166 are not fixed per database and are not set by this command\&. If you want to make them the default for a specific database, you can use
 167 ALTER DATABASE \&.\&.\&. SET\&.
 168 .sp .5v
 169 .RE
 170 .RE
 171 .PP
 172 \fIlc_collate\fR
 173 .RS 4
 174 Sets
 175 LC_COLLATE
 176 in the database server\*(Aqs operating system environment\&. The default is the setting of
 177 \fIlocale\fR
 178 if specified, otherwise the same setting as the template database\&. See below for additional restrictions\&.
 179 .sp
 180 If
 181 \fIlocale_provider\fR
 182 is
 183 libc, also sets the default collation order to use in the new database, overriding the setting
 184 \fIlocale\fR\&.
 185 .RE
 186 .PP
 187 \fIlc_ctype\fR
 188 .RS 4
 189 Sets
 190 LC_CTYPE
 191 in the database server\*(Aqs operating system environment\&. The default is the setting of
 192 \fIlocale\fR
 193 if specified, otherwise the same setting as the template database\&. See below for additional restrictions\&.
 194 .sp
 195 If
 196 \fIlocale_provider\fR
 197 is
 198 libc, also sets the default character classification to use in the new database, overriding the setting
 199 \fIlocale\fR\&.
 200 .RE
 201 .PP
 202 \fIbuiltin_locale\fR
 203 .RS 4
 204 Specifies the builtin provider locale for the database default collation order and character classification, overriding the setting
 205 \fIlocale\fR\&. The
 206 locale provider
 207 must be
 208 builtin\&. The default is the setting of
 209 \fIlocale\fR
 210 if specified; otherwise the same setting as the template database\&.
 211 .sp
 212 The locales available for the
 213 builtin
 214 provider are
 215 C,
 216 C\&.UTF\-8
 217 and
 218 PG_UNICODE_FAST\&.
 219 .RE
 220 .PP
 221 \fIicu_locale\fR
 222 .RS 4
 223 Specifies the ICU locale (see
 224 Section\ \&23.2.2.3.2) for the database default collation order and character classification, overriding the setting
 225 \fIlocale\fR\&. The
 226 locale provider
 227 must be ICU\&. The default is the setting of
 228 \fIlocale\fR
 229 if specified; otherwise the same setting as the template database\&.
 230 .RE
 231 .PP
 232 \fIicu_rules\fR
 233 .RS 4
 234 Specifies additional collation rules to customize the behavior of the default collation of this database\&. This is supported for ICU only\&. See
 235 Section\ \&23.2.3.4
 236 for details\&.
 237 .RE
 238 .PP
 239 \fIlocale_provider\fR
 240 .RS 4
 241 Specifies the provider to use for the default collation in this database\&. Possible values are
 242 builtin,
 243 icu
 244 (if the server was built with ICU support) or
 245 libc\&. By default, the provider is the same as that of the
 246 \fItemplate\fR\&. See
 247 Section\ \&23.1.4
 248 for details\&.
 249 .RE
 250 .PP
 251 \fIcollation_version\fR
 252 .RS 4
 253 Specifies the collation version string to store with the database\&. Normally, this should be omitted, which will cause the version to be computed from the actual version of the database collation as provided by the operating system\&. This option is intended to be used by
 254 \fBpg_upgrade\fR
 255 for copying the version from an existing installation\&.
 256 .sp
 257 See also
 258 ALTER DATABASE (\fBALTER_DATABASE\fR(7))
 259 for how to handle database collation version mismatches\&.
 260 .RE
 261 .PP
 262 \fItablespace_name\fR
 263 .RS 4
 264 The name of the tablespace that will be associated with the new database, or
 265 DEFAULT
 266 to use the template database\*(Aqs tablespace\&. This tablespace will be the default tablespace used for objects created in this database\&. See
 267 CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7))
 268 for more information\&.
 269 .RE
 270 .PP
 271 \fIallowconn\fR
 272 .RS 4
 273 If false then no one can connect to this database\&. The default is true, allowing connections (except as restricted by other mechanisms, such as
 274 GRANT/REVOKE CONNECT)\&.
 275 .RE
 276 .PP
 277 \fIconnlimit\fR
 278 .RS 4
 279 How many concurrent connections can be made to this database\&. \-1 (the default) means no limit\&.
 280 .RE
 281 .PP
 282 \fIistemplate\fR
 283 .RS 4
 284 If true, then this database can be cloned by any user with
 285 CREATEDB
 286 privileges; if false (the default), then only superusers or the owner of the database can clone it\&.
 287 .RE
 288 .PP
 289 \fIoid\fR
 290 .RS 4
 291 The object identifier to be used for the new database\&. If this parameter is not specified,
 292 PostgreSQL
 293 will choose a suitable OID automatically\&. This parameter is primarily intended for internal use by
 294 pg_upgrade, and only
 295 pg_upgrade
 296 can specify a value less than 16384\&.
 297 .RE
 298 .PP
 299 Optional parameters can be written in any order, not only the order illustrated above\&.
 300 .SH "NOTES"
 301 .PP
 302 \fBCREATE DATABASE\fR
 303 cannot be executed inside a transaction block\&.
 304 .PP
 305 Errors along the line of
 306 \(lqcould not initialize database directory\(rq
 307 are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems\&.
 308 .PP
 309 Use
 310 \fBDROP DATABASE\fR
 311 to remove a database\&.
 312 .PP
 313 The program
 314 \fBcreatedb\fR(1)
 315 is a wrapper program around this command, provided for convenience\&.
 316 .PP
 317 Database\-level configuration parameters (set via
 318 \fBALTER DATABASE\fR) and database\-level permissions (set via
 319 \fBGRANT\fR) are not copied from the template database\&.
 320 .PP
 321 Although it is possible to copy a database other than
 322 template1
 323 by specifying its name as the template, this is not (yet) intended as a general\-purpose
 324 \(lq\fBCOPY DATABASE\fR\(rq
 325 facility\&. The principal limitation is that no other sessions can be connected to the template database while it is being copied\&.
 326 \fBCREATE DATABASE\fR
 327 will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out until
 328 \fBCREATE DATABASE\fR
 329 completes\&. See
 330 Section\ \&22.3
 331 for more information\&.
 332 .PP
 333 The character set encoding specified for the new database must be compatible with the chosen locale settings (LC_COLLATE
 334 and
 335 LC_CTYPE)\&. If the locale is
 336 C
 337 (or equivalently
 338 POSIX), then all encodings are allowed, but for other locale settings there is only one encoding that will work properly\&. (On Windows, however, UTF\-8 encoding can be used with any locale\&.)
 339 \fBCREATE DATABASE\fR
 340 will allow superusers to specify
 341 SQL_ASCII
 342 encoding regardless of the locale settings, but this choice is deprecated and may result in misbehavior of character\-string functions if data that is not encoding\-compatible with the locale is stored in the database\&.
 343 .PP
 344 The encoding and locale settings must match those of the template database, except when
 345 template0
 346 is used as template\&. This is because other databases might contain data that does not match the specified encoding, or might contain indexes whose sort ordering is affected by
 347 LC_COLLATE
 348 and
 349 LC_CTYPE\&. Copying such data would result in a database that is corrupt according to the new settings\&.
 350 template0, however, is known to not contain any data or indexes that would be affected\&.
 351 .PP
 352 There is currently no option to use a database locale with nondeterministic comparisons (see
 353 \fBCREATE COLLATION\fR
 354 for an explanation)\&. If this is needed, then per\-column collations would need to be used\&.
 355 .PP
 356 The
 357 CONNECTION LIMIT
 358 option is only enforced approximately; if two new sessions start at about the same time when just one connection
 359 \(lqslot\(rq
 360 remains for the database, it is possible that both will fail\&. Also, the limit is not enforced against superusers or background worker processes\&.
 361 .SH "EXAMPLES"
 362 .PP
 363 To create a new database:
 364 .sp
 365 .if n \{\
 366 .RS 4
 367 .\}
 368 .nf
 369 CREATE DATABASE lusiadas;
 370 .fi
 371 .if n \{\
 372 .RE
 373 .\}
 374 .PP
 375 To create a database
 376 sales
 377 owned by user
 378 salesapp
 379 with a default tablespace of
 380 salesspace:
 381 .sp
 382 .if n \{\
 383 .RS 4
 384 .\}
 385 .nf
 386 CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 387 .fi
 388 .if n \{\
 389 .RE
 390 .\}
 391 .PP
 392 To create a database
 393 music
 394 with a different locale:
 395 .sp
 396 .if n \{\
 397 .RS 4
 398 .\}
 399 .nf
 400 CREATE DATABASE music
 401     LOCALE \*(Aqsv_SE\&.utf8\*(Aq
 402     TEMPLATE template0;
 403 .fi
 404 .if n \{\
 405 .RE
 406 .\}
 407 .sp
 408 In this example, the
 409 TEMPLATE template0
 410 clause is required if the specified locale is different from the one in
 411 template1\&. (If it is not, then specifying the locale explicitly is redundant\&.)
 412 .PP
 413 To create a database
 414 music2
 415 with a different locale and a different character set encoding:
 416 .sp
 417 .if n \{\
 418 .RS 4
 419 .\}
 420 .nf
 421 CREATE DATABASE music2
 422     LOCALE \*(Aqsv_SE\&.iso885915\*(Aq
 423     ENCODING LATIN9
 424     TEMPLATE template0;
 425 .fi
 426 .if n \{\
 427 .RE
 428 .\}
 429 .sp
 430 The specified locale and encoding settings must match, or an error will be reported\&.
 431 .PP
 432 Note that locale names are specific to the operating system, so that the above commands might not work in the same way everywhere\&.
 433 .SH "COMPATIBILITY"
 434 .PP
 435 There is no
 436 \fBCREATE DATABASE\fR
 437 statement in the SQL standard\&. Databases are equivalent to catalogs, whose creation is implementation\-defined\&.
 438 .SH "SEE ALSO"
 439 ALTER DATABASE (\fBALTER_DATABASE\fR(7)), DROP DATABASE (\fBDROP_DATABASE\fR(7))