begriffs open source - ai-pg/blob - full-docs/txt/sql-createdatabase.txt

   1
   2 CREATE DATABASE
   3
   4    CREATE DATABASE — create a new database
   5
   6 Synopsis
   7
   8 CREATE DATABASE name
   9     [ WITH ] [ OWNER [=] user_name ]
  10            [ TEMPLATE [=] template ]
  11            [ ENCODING [=] encoding ]
  12            [ STRATEGY [=] strategy ]
  13            [ LOCALE [=] locale ]
  14            [ LC_COLLATE [=] lc_collate ]
  15            [ LC_CTYPE [=] lc_ctype ]
  16            [ BUILTIN_LOCALE [=] builtin_locale ]
  17            [ ICU_LOCALE [=] icu_locale ]
  18            [ ICU_RULES [=] icu_rules ]
  19            [ LOCALE_PROVIDER [=] locale_provider ]
  20            [ COLLATION_VERSION = collation_version ]
  21            [ TABLESPACE [=] tablespace_name ]
  22            [ ALLOW_CONNECTIONS [=] allowconn ]
  23            [ CONNECTION LIMIT [=] connlimit ]
  24            [ IS_TEMPLATE [=] istemplate ]
  25            [ OID [=] oid ]
  26
  27 Description
  28
  29    CREATE DATABASE creates a new PostgreSQL database.
  30
  31    To create a database, you must be a superuser or have the special
  32    CREATEDB privilege. See CREATE ROLE.
  33
  34    By default, the new database will be created by cloning the standard
  35    system database template1. A different template can be specified by
  36    writing TEMPLATE name. In particular, by writing TEMPLATE template0,
  37    you can create a pristine database (one where no user-defined objects
  38    exist and where the system objects have not been altered) containing
  39    only the standard objects predefined by your version of PostgreSQL.
  40    This is useful if you wish to avoid copying any installation-local
  41    objects that might have been added to template1.
  42
  43 Parameters
  44
  45    name #
  46           The name of a database to create.
  47
  48    user_name #
  49           The role name of the user who will own the new database, or
  50           DEFAULT to use the default (namely, the user executing the
  51           command). To create a database owned by another role, you must
  52           be able to SET ROLE to that role.
  53
  54    template #
  55           The name of the template from which to create the new database,
  56           or DEFAULT to use the default template (template1).
  57
  58    encoding #
  59           Character set encoding to use in the new database. Specify a
  60           string constant (e.g., 'SQL_ASCII'), or an integer encoding
  61           number, or DEFAULT to use the default encoding (namely, the
  62           encoding of the template database). The character sets supported
  63           by the PostgreSQL server are described in Section 23.3.1. See
  64           below for additional restrictions.
  65
  66    strategy #
  67           Strategy to be used in creating the new database. If the WAL_LOG
  68           strategy is used, the database will be copied block by block and
  69           each block will be separately written to the write-ahead log.
  70           This is the most efficient strategy in cases where the template
  71           database is small, and therefore it is the default. The older
  72           FILE_COPY strategy is also available. This strategy writes a
  73           small record to the write-ahead log for each tablespace used by
  74           the target database. Each such record represents copying an
  75           entire directory to a new location at the filesystem level.
  76           While this does reduce the write-ahead log volume substantially,
  77           especially if the template database is large, it also forces the
  78           system to perform a checkpoint both before and after the
  79           creation of the new database. In some situations, this may have
  80           a noticeable negative impact on overall system performance. The
  81           FILE_COPY strategy is affected by the file_copy_method setting.
  82
  83    locale #
  84           Sets the default collation order and character classification in
  85           the new database. Collation affects the sort order applied to
  86           strings, e.g., in queries with ORDER BY, as well as the order
  87           used in indexes on text columns. Character classification
  88           affects the categorization of characters, e.g., lower, upper,
  89           and digit. Also sets the associated aspects of the operating
  90           system environment, LC_COLLATE and LC_CTYPE. The default is the
  91           same setting as the template database. See Section 23.2.2.3.1
  92           and Section 23.2.2.3.2 for details.
  93
  94           Can be overridden by setting lc_collate, lc_ctype,
  95           builtin_locale, or icu_locale individually.
  96
  97           If locale_provider is builtin, then locale or builtin_locale
  98           must be specified and set to either C, C.UTF-8, or
  99           PG_UNICODE_FAST.
 100
 101 Tip
 102
 103           The other locale settings lc_messages, lc_monetary, lc_numeric,
 104           and lc_time are not fixed per database and are not set by this
 105           command. If you want to make them the default for a specific
 106           database, you can use ALTER DATABASE ... SET.
 107
 108    lc_collate #
 109           Sets LC_COLLATE in the database server's operating system
 110           environment. The default is the setting of locale if specified,
 111           otherwise the same setting as the template database. See below
 112           for additional restrictions.
 113
 114           If locale_provider is libc, also sets the default collation
 115           order to use in the new database, overriding the setting locale.
 116
 117    lc_ctype #
 118           Sets LC_CTYPE in the database server's operating system
 119           environment. The default is the setting of locale if specified,
 120           otherwise the same setting as the template database. See below
 121           for additional restrictions.
 122
 123           If locale_provider is libc, also sets the default character
 124           classification to use in the new database, overriding the
 125           setting locale.
 126
 127    builtin_locale #
 128           Specifies the builtin provider locale for the database default
 129           collation order and character classification, overriding the
 130           setting locale. The locale provider must be builtin. The default
 131           is the setting of locale if specified; otherwise the same
 132           setting as the template database.
 133
 134           The locales available for the builtin provider are C, C.UTF-8
 135           and PG_UNICODE_FAST.
 136
 137    icu_locale #
 138           Specifies the ICU locale (see Section 23.2.2.3.2) for the
 139           database default collation order and character classification,
 140           overriding the setting locale. The locale provider must be ICU.
 141           The default is the setting of locale if specified; otherwise the
 142           same setting as the template database.
 143
 144    icu_rules #
 145           Specifies additional collation rules to customize the behavior
 146           of the default collation of this database. This is supported for
 147           ICU only. See Section 23.2.3.4 for details.
 148
 149    locale_provider #
 150           Specifies the provider to use for the default collation in this
 151           database. Possible values are builtin, icu (if the server was
 152           built with ICU support) or libc. By default, the provider is the
 153           same as that of the template. See Section 23.1.4 for details.
 154
 155    collation_version #
 156           Specifies the collation version string to store with the
 157           database. Normally, this should be omitted, which will cause the
 158           version to be computed from the actual version of the database
 159           collation as provided by the operating system. This option is
 160           intended to be used by pg_upgrade for copying the version from
 161           an existing installation.
 162
 163           See also ALTER DATABASE for how to handle database collation
 164           version mismatches.
 165
 166    tablespace_name #
 167           The name of the tablespace that will be associated with the new
 168           database, or DEFAULT to use the template database's tablespace.
 169           This tablespace will be the default tablespace used for objects
 170           created in this database. See CREATE TABLESPACE for more
 171           information.
 172
 173    allowconn #
 174           If false then no one can connect to this database. The default
 175           is true, allowing connections (except as restricted by other
 176           mechanisms, such as GRANT/REVOKE CONNECT).
 177
 178    connlimit #
 179           How many concurrent connections can be made to this database. -1
 180           (the default) means no limit.
 181
 182    istemplate #
 183           If true, then this database can be cloned by any user with
 184           CREATEDB privileges; if false (the default), then only
 185           superusers or the owner of the database can clone it.
 186
 187    oid #
 188           The object identifier to be used for the new database. If this
 189           parameter is not specified, PostgreSQL will choose a suitable
 190           OID automatically. This parameter is primarily intended for
 191           internal use by pg_upgrade, and only pg_upgrade can specify a
 192           value less than 16384.
 193
 194    Optional parameters can be written in any order, not only the order
 195    illustrated above.
 196
 197 Notes
 198
 199    CREATE DATABASE cannot be executed inside a transaction block.
 200
 201    Errors along the line of “could not initialize database directory” are
 202    most likely related to insufficient permissions on the data directory,
 203    a full disk, or other file system problems.
 204
 205    Use DROP DATABASE to remove a database.
 206
 207    The program createdb is a wrapper program around this command, provided
 208    for convenience.
 209
 210    Database-level configuration parameters (set via ALTER DATABASE) and
 211    database-level permissions (set via GRANT) are not copied from the
 212    template database.
 213
 214    Although it is possible to copy a database other than template1 by
 215    specifying its name as the template, this is not (yet) intended as a
 216    general-purpose “COPY DATABASE” facility. The principal limitation is
 217    that no other sessions can be connected to the template database while
 218    it is being copied. CREATE DATABASE will fail if any other connection
 219    exists when it starts; otherwise, new connections to the template
 220    database are locked out until CREATE DATABASE completes. See
 221    Section 22.3 for more information.
 222
 223    The character set encoding specified for the new database must be
 224    compatible with the chosen locale settings (LC_COLLATE and LC_CTYPE).
 225    If the locale is C (or equivalently POSIX), then all encodings are
 226    allowed, but for other locale settings there is only one encoding that
 227    will work properly. (On Windows, however, UTF-8 encoding can be used
 228    with any locale.) CREATE DATABASE will allow superusers to specify
 229    SQL_ASCII encoding regardless of the locale settings, but this choice
 230    is deprecated and may result in misbehavior of character-string
 231    functions if data that is not encoding-compatible with the locale is
 232    stored in the database.
 233
 234    The encoding and locale settings must match those of the template
 235    database, except when template0 is used as template. This is because
 236    other databases might contain data that does not match the specified
 237    encoding, or might contain indexes whose sort ordering is affected by
 238    LC_COLLATE and LC_CTYPE. Copying such data would result in a database
 239    that is corrupt according to the new settings. template0, however, is
 240    known to not contain any data or indexes that would be affected.
 241
 242    There is currently no option to use a database locale with
 243    nondeterministic comparisons (see CREATE COLLATION for an explanation).
 244    If this is needed, then per-column collations would need to be used.
 245
 246    The CONNECTION LIMIT option is only enforced approximately; if two new
 247    sessions start at about the same time when just one connection “slot”
 248    remains for the database, it is possible that both will fail. Also, the
 249    limit is not enforced against superusers or background worker
 250    processes.
 251
 252 Examples
 253
 254    To create a new database:
 255 CREATE DATABASE lusiadas;
 256
 257    To create a database sales owned by user salesapp with a default
 258    tablespace of salesspace:
 259 CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 260
 261    To create a database music with a different locale:
 262 CREATE DATABASE music
 263     LOCALE 'sv_SE.utf8'
 264     TEMPLATE template0;
 265
 266    In this example, the TEMPLATE template0 clause is required if the
 267    specified locale is different from the one in template1. (If it is not,
 268    then specifying the locale explicitly is redundant.)
 269
 270    To create a database music2 with a different locale and a different
 271    character set encoding:
 272 CREATE DATABASE music2
 273     LOCALE 'sv_SE.iso885915'
 274     ENCODING LATIN9
 275     TEMPLATE template0;
 276
 277    The specified locale and encoding settings must match, or an error will
 278    be reported.
 279
 280    Note that locale names are specific to the operating system, so that
 281    the above commands might not work in the same way everywhere.
 282
 283 Compatibility
 284
 285    There is no CREATE DATABASE statement in the SQL standard. Databases
 286    are equivalent to catalogs, whose creation is implementation-defined.
 287
 288 See Also
 289
 290    ALTER DATABASE, DROP DATABASE