begriffs open source - ai-pg/blob - full-docs/man1/createdb.1

   1 '\" t
   2 .\"     Title: createdb
   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 "CREATEDB" "1" "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 createdb \- create a new PostgreSQL database
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBcreatedb\fR\ 'u
  34 \fBcreatedb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIdbname\fR\ [\fIdescription\fR]]
  35 .SH "DESCRIPTION"
  36 .PP
  37 createdb
  38 creates a new
  39 PostgreSQL
  40 database\&.
  41 .PP
  42 Normally, the database user who executes this command becomes the owner of the new database\&. However, a different owner can be specified via the
  43 \fB\-O\fR
  44 option, if the executing user has appropriate privileges\&.
  45 .PP
  46 createdb
  47 is a wrapper around the
  48 SQL
  49 command
  50 \fBCREATE DATABASE\fR\&. There is no effective difference between creating databases via this utility and via other methods for accessing the server\&.
  51 .SH "OPTIONS"
  52 .PP
  53 createdb
  54 accepts the following command\-line arguments:
  55 .PP
  56 \fIdbname\fR
  57 .RS 4
  58 Specifies the name of the database to be created\&. The name must be unique among all
  59 PostgreSQL
  60 databases in this cluster\&. The default is to create a database with the same name as the current system user\&.
  61 .RE
  62 .PP
  63 \fIdescription\fR
  64 .RS 4
  65 Specifies a comment to be associated with the newly created database\&.
  66 .RE
  67 .PP
  68 \fB\-D \fR\fB\fItablespace\fR\fR
  69 .br
  70 \fB\-\-tablespace=\fR\fB\fItablespace\fR\fR
  71 .RS 4
  72 Specifies the default tablespace for the database\&. (This name is processed as a double\-quoted identifier\&.)
  73 .RE
  74 .PP
  75 \fB\-e\fR
  76 .br
  77 \fB\-\-echo\fR
  78 .RS 4
  79 Echo the commands that
  80 createdb
  81 generates and sends to the server\&.
  82 .RE
  83 .PP
  84 \fB\-E \fR\fB\fIencoding\fR\fR
  85 .br
  86 \fB\-\-encoding=\fR\fB\fIencoding\fR\fR
  87 .RS 4
  88 Specifies the character encoding scheme to be used in this database\&. The character sets supported by the
  89 PostgreSQL
  90 server are described in
  91 Section\ \&23.3.1\&.
  92 .RE
  93 .PP
  94 \fB\-l \fR\fB\fIlocale\fR\fR
  95 .br
  96 \fB\-\-locale=\fR\fB\fIlocale\fR\fR
  97 .RS 4
  98 Specifies the locale to be used in this database\&. This is equivalent to specifying
  99 \fB\-\-lc\-collate\fR,
 100 \fB\-\-lc\-ctype\fR, and
 101 \fB\-\-icu\-locale\fR
 102 to the same value\&. Some locales are only valid for ICU and must be set with
 103 \fB\-\-icu\-locale\fR\&.
 104 .RE
 105 .PP
 106 \fB\-\-lc\-collate=\fR\fB\fIlocale\fR\fR
 107 .RS 4
 108 Specifies the LC_COLLATE setting to be used in this database\&.
 109 .RE
 110 .PP
 111 \fB\-\-lc\-ctype=\fR\fB\fIlocale\fR\fR
 112 .RS 4
 113 Specifies the LC_CTYPE setting to be used in this database\&.
 114 .RE
 115 .PP
 116 \fB\-\-builtin\-locale=\fR\fB\fIlocale\fR\fR
 117 .RS 4
 118 Specifies the locale name when the builtin provider is used\&. Locale support is described in
 119 Section\ \&23.1\&.
 120 .RE
 121 .PP
 122 \fB\-\-icu\-locale=\fR\fB\fIlocale\fR\fR
 123 .RS 4
 124 Specifies the ICU locale ID to be used in this database, if the ICU locale provider is selected\&.
 125 .RE
 126 .PP
 127 \fB\-\-icu\-rules=\fR\fB\fIrules\fR\fR
 128 .RS 4
 129 Specifies additional collation rules to customize the behavior of the default collation of this database\&. This is supported for ICU only\&.
 130 .RE
 131 .PP
 132 \fB\-\-locale\-provider={\fR\fBbuiltin\fR\fB|\fR\fBlibc\fR\fB|\fR\fBicu\fR\fB}\fR
 133 .RS 4
 134 Specifies the locale provider for the database\*(Aqs default collation\&.
 135 .RE
 136 .PP
 137 \fB\-O \fR\fB\fIowner\fR\fR
 138 .br
 139 \fB\-\-owner=\fR\fB\fIowner\fR\fR
 140 .RS 4
 141 Specifies the database user who will own the new database\&. (This name is processed as a double\-quoted identifier\&.)
 142 .RE
 143 .PP
 144 \fB\-S \fR\fB\fIstrategy\fR\fR
 145 .br
 146 \fB\-\-strategy=\fR\fB\fIstrategy\fR\fR
 147 .RS 4
 148 Specifies the database creation strategy\&. See
 149 CREATE DATABASE STRATEGY
 150 for more details\&.
 151 .RE
 152 .PP
 153 \fB\-T \fR\fB\fItemplate\fR\fR
 154 .br
 155 \fB\-\-template=\fR\fB\fItemplate\fR\fR
 156 .RS 4
 157 Specifies the template database from which to build this database\&. (This name is processed as a double\-quoted identifier\&.)
 158 .RE
 159 .PP
 160 \fB\-V\fR
 161 .br
 162 \fB\-\-version\fR
 163 .RS 4
 164 Print the
 165 createdb
 166 version and exit\&.
 167 .RE
 168 .PP
 169 \fB\-?\fR
 170 .br
 171 \fB\-\-help\fR
 172 .RS 4
 173 Show help about
 174 createdb
 175 command line arguments, and exit\&.
 176 .RE
 177 .PP
 178 The options
 179 \fB\-D\fR,
 180 \fB\-l\fR,
 181 \fB\-E\fR,
 182 \fB\-O\fR, and
 183 \fB\-T\fR
 184 correspond to options of the underlying SQL command
 185 \fBCREATE DATABASE\fR; see there for more information about them\&.
 186 .PP
 187 createdb
 188 also accepts the following command\-line arguments for connection parameters:
 189 .PP
 190 \fB\-h \fR\fB\fIhost\fR\fR
 191 .br
 192 \fB\-\-host=\fR\fB\fIhost\fR\fR
 193 .RS 4
 194 Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&.
 195 .RE
 196 .PP
 197 \fB\-p \fR\fB\fIport\fR\fR
 198 .br
 199 \fB\-\-port=\fR\fB\fIport\fR\fR
 200 .RS 4
 201 Specifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections\&.
 202 .RE
 203 .PP
 204 \fB\-U \fR\fB\fIusername\fR\fR
 205 .br
 206 \fB\-\-username=\fR\fB\fIusername\fR\fR
 207 .RS 4
 208 User name to connect as\&.
 209 .RE
 210 .PP
 211 \fB\-w\fR
 212 .br
 213 \fB\-\-no\-password\fR
 214 .RS 4
 215 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
 216 \&.pgpass
 217 file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&.
 218 .RE
 219 .PP
 220 \fB\-W\fR
 221 .br
 222 \fB\-\-password\fR
 223 .RS 4
 224 Force
 225 createdb
 226 to prompt for a password before connecting to a database\&.
 227 .sp
 228 This option is never essential, since
 229 createdb
 230 will automatically prompt for a password if the server demands password authentication\&. However,
 231 createdb
 232 will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
 233 \fB\-W\fR
 234 to avoid the extra connection attempt\&.
 235 .RE
 236 .PP
 237 \fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR
 238 .RS 4
 239 Specifies the name of the database to connect to when creating the new database\&. If not specified, the
 240 postgres
 241 database will be used; if that does not exist (or if it is the name of the new database being created),
 242 template1
 243 will be used\&. This can be a
 244 connection string\&. If so, connection string parameters will override any conflicting command line options\&.
 245 .RE
 246 .SH "ENVIRONMENT"
 247 .PP
 248 \fBPGDATABASE\fR
 249 .RS 4
 250 If set, the name of the database to create, unless overridden on the command line\&.
 251 .RE
 252 .PP
 253 \fBPGHOST\fR
 254 .br
 255 \fBPGPORT\fR
 256 .br
 257 \fBPGUSER\fR
 258 .RS 4
 259 Default connection parameters\&.
 260 \fBPGUSER\fR
 261 also determines the name of the database to create, if it is not specified on the command line or by
 262 \fBPGDATABASE\fR\&.
 263 .RE
 264 .PP
 265 \fBPG_COLOR\fR
 266 .RS 4
 267 Specifies whether to use color in diagnostic messages\&. Possible values are
 268 always,
 269 auto
 270 and
 271 never\&.
 272 .RE
 273 .PP
 274 This utility, like most other
 275 PostgreSQL
 276 utilities, also uses the environment variables supported by
 277 libpq
 278 (see
 279 Section\ \&32.15)\&.
 280 .SH "DIAGNOSTICS"
 281 .PP
 282 In case of difficulty, see
 283 CREATE DATABASE (\fBCREATE_DATABASE\fR(7))
 284 and
 285 \fBpsql\fR(1)
 286 for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the
 287 libpq
 288 front\-end library will apply\&.
 289 .SH "EXAMPLES"
 290 .PP
 291 To create the database
 292 demo
 293 using the default database server:
 294 .sp
 295 .if n \{\
 296 .RS 4
 297 .\}
 298 .nf
 299 $ \fBcreatedb demo\fR
 300 .fi
 301 .if n \{\
 302 .RE
 303 .\}
 304 .PP
 305 To create the database
 306 demo
 307 using the server on host
 308 eden, port 5000, using the
 309 template0
 310 template database, here is the command\-line command and the underlying SQL command:
 311 .sp
 312 .if n \{\
 313 .RS 4
 314 .\}
 315 .nf
 316 $ \fBcreatedb \-p 5000 \-h eden \-T template0 \-e demo\fR
 317 CREATE DATABASE demo TEMPLATE template0;
 318 .fi
 319 .if n \{\
 320 .RE
 321 .\}
 322 .SH "SEE ALSO"
 323 \fBdropdb\fR(1), CREATE DATABASE (\fBCREATE_DATABASE\fR(7))