1<!-- 2doc/src/sgml/ref/createdb.sgml 3PostgreSQL documentation 4--> 5 6<refentry id="APP-CREATEDB"> 7 <indexterm zone="app-createdb"> 8 <primary>createdb</primary> 9 </indexterm> 10 11 <refmeta> 12 <refentrytitle><application>createdb</application></refentrytitle> 13 <manvolnum>1</manvolnum> 14 <refmiscinfo>Application</refmiscinfo> 15 </refmeta> 16 17 <refnamediv> 18 <refname>createdb</refname> 19 <refpurpose>create a new <productname>PostgreSQL</productname> database</refpurpose> 20 </refnamediv> 21 22 <refsynopsisdiv> 23 <cmdsynopsis> 24 <command>createdb</command> 25 <arg rep="repeat"><replaceable>connection-option</replaceable></arg> 26 <arg rep="repeat"><replaceable>option</replaceable></arg> 27 <arg choice="opt"><replaceable>dbname</replaceable> 28 <arg choice="opt"><replaceable>description</replaceable></arg></arg> 29 </cmdsynopsis> 30 </refsynopsisdiv> 31 32 33 <refsect1 id="R1-APP-CREATEDB-1"> 34 <title> 35 Description 36 </title> 37 <para> 38 <application>createdb</application> creates a new <productname>PostgreSQL</productname> 39 database. 40 </para> 41 42 <para> 43 Normally, the database user who executes this command becomes the owner of 44 the new database. 45 However, a different owner can be specified via the <option>-O</option> 46 option, if the executing user has appropriate privileges. 47 </para> 48 49 <para> 50 <application>createdb</application> is a wrapper around the 51 <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE">. 52 There is no effective difference between creating databases via 53 this utility and via other methods for accessing the server. 54 </para> 55 56 </refsect1> 57 58 59 <refsect1> 60 <title>Options</title> 61 62 <para> 63 <application>createdb</application> accepts the following command-line arguments: 64 65 <variablelist> 66 <varlistentry> 67 <term><replaceable class="parameter">dbname</replaceable></term> 68 <listitem> 69 <para> 70 Specifies the name of the database to be created. The name must be 71 unique among all <productname>PostgreSQL</productname> databases in this cluster. 72 The default is to create a database with the same name as the 73 current system user. 74 </para> 75 </listitem> 76 </varlistentry> 77 78 <varlistentry> 79 <term><replaceable class="parameter">description</replaceable></term> 80 <listitem> 81 <para> 82 Specifies a comment to be associated with the newly created 83 database. 84 </para> 85 </listitem> 86 </varlistentry> 87 88 <varlistentry> 89 <term><option>-D <replaceable class="parameter">tablespace</replaceable></></term> 90 <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></></term> 91 <listitem> 92 <para> 93 Specifies the default tablespace for the database. (This name 94 is processed as a double-quoted identifier.) 95 </para> 96 </listitem> 97 </varlistentry> 98 99 <varlistentry> 100 <term><option>-e</></term> 101 <term><option>--echo</></term> 102 <listitem> 103 <para> 104 Echo the commands that <application>createdb</application> generates 105 and sends to the server. 106 </para> 107 </listitem> 108 </varlistentry> 109 110 <varlistentry> 111 <term><option>-E <replaceable class="parameter">encoding</replaceable></></term> 112 <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></></term> 113 <listitem> 114 <para> 115 Specifies the character encoding scheme to be used in this 116 database. The character sets supported by the 117 <productname>PostgreSQL</productname> server are described in 118 <xref linkend="multibyte-charset-supported">. 119 </para> 120 </listitem> 121 </varlistentry> 122 123 <varlistentry> 124 <term><option>-l <replaceable class="parameter">locale</replaceable></></term> 125 <term><option>--locale=<replaceable class="parameter">locale</replaceable></></term> 126 <listitem> 127 <para> 128 Specifies the locale to be used in this database. This is equivalent 129 to specifying both <option>--lc-collate</option> and <option>--lc-ctype</option>. 130 </para> 131 </listitem> 132 </varlistentry> 133 134 <varlistentry> 135 <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></></term> 136 <listitem> 137 <para> 138 Specifies the LC_COLLATE setting to be used in this database. 139 </para> 140 </listitem> 141 </varlistentry> 142 143 <varlistentry> 144 <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></></term> 145 <listitem> 146 <para> 147 Specifies the LC_CTYPE setting to be used in this database. 148 </para> 149 </listitem> 150 </varlistentry> 151 152 <varlistentry> 153 <term><option>-O <replaceable class="parameter">owner</replaceable></></term> 154 <term><option>--owner=<replaceable class="parameter">owner</replaceable></></term> 155 <listitem> 156 <para> 157 Specifies the database user who will own the new database. 158 (This name is processed as a double-quoted identifier.) 159 </para> 160 </listitem> 161 </varlistentry> 162 163 <varlistentry> 164 <term><option>-T <replaceable class="parameter">template</replaceable></></term> 165 <term><option>--template=<replaceable class="parameter">template</replaceable></></term> 166 <listitem> 167 <para> 168 Specifies the template database from which to build this 169 database. (This name is processed as a double-quoted identifier.) 170 </para> 171 </listitem> 172 </varlistentry> 173 174 <varlistentry> 175 <term><option>-V</></term> 176 <term><option>--version</></term> 177 <listitem> 178 <para> 179 Print the <application>createdb</application> version and exit. 180 </para> 181 </listitem> 182 </varlistentry> 183 184 <varlistentry> 185 <term><option>-?</></term> 186 <term><option>--help</></term> 187 <listitem> 188 <para> 189 Show help about <application>createdb</application> command line 190 arguments, and exit. 191 </para> 192 </listitem> 193 </varlistentry> 194 195 </variablelist> 196 </para> 197 198 <para> 199 The options <option>-D</option>, <option>-l</option>, <option>-E</option>, 200 <option>-O</option>, and 201 <option>-T</option> correspond to options of the underlying 202 SQL command <xref linkend="SQL-CREATEDATABASE">; see there for more information 203 about them. 204 </para> 205 206 <para> 207 <application>createdb</application> also accepts the following 208 command-line arguments for connection parameters: 209 210 <variablelist> 211 <varlistentry> 212 <term><option>-h <replaceable class="parameter">host</replaceable></></term> 213 <term><option>--host=<replaceable class="parameter">host</replaceable></></term> 214 <listitem> 215 <para> 216 Specifies the host name of the machine on which the 217 server is running. If the value begins with a slash, it is used 218 as the directory for the Unix domain socket. 219 </para> 220 </listitem> 221 </varlistentry> 222 223 <varlistentry> 224 <term><option>-p <replaceable class="parameter">port</replaceable></></term> 225 <term><option>--port=<replaceable class="parameter">port</replaceable></></term> 226 <listitem> 227 <para> 228 Specifies the TCP port or the local Unix domain socket file 229 extension on which the server is listening for connections. 230 </para> 231 </listitem> 232 </varlistentry> 233 234 <varlistentry> 235 <term><option>-U <replaceable class="parameter">username</replaceable></></term> 236 <term><option>--username=<replaceable class="parameter">username</replaceable></></term> 237 <listitem> 238 <para> 239 User name to connect as. 240 </para> 241 </listitem> 242 </varlistentry> 243 244 <varlistentry> 245 <term><option>-w</></term> 246 <term><option>--no-password</></term> 247 <listitem> 248 <para> 249 Never issue a password prompt. If the server requires 250 password authentication and a password is not available by 251 other means such as a <filename>.pgpass</filename> file, the 252 connection attempt will fail. This option can be useful in 253 batch jobs and scripts where no user is present to enter a 254 password. 255 </para> 256 </listitem> 257 </varlistentry> 258 259 <varlistentry> 260 <term><option>-W</></term> 261 <term><option>--password</></term> 262 <listitem> 263 <para> 264 Force <application>createdb</application> to prompt for a 265 password before connecting to a database. 266 </para> 267 268 <para> 269 This option is never essential, since 270 <application>createdb</application> will automatically prompt 271 for a password if the server demands password authentication. 272 However, <application>createdb</application> will waste a 273 connection attempt finding out that the server wants a password. 274 In some cases it is worth typing <option>-W</> to avoid the extra 275 connection attempt. 276 </para> 277 </listitem> 278 </varlistentry> 279 280 <varlistentry> 281 <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> 282 <listitem> 283 <para> 284 Specifies the name of the database to connect to when creating the 285 new database. If not specified, the <literal>postgres</literal> 286 database will be used; if that does not exist (or if it is the name 287 of the new database being created), <literal>template1</literal> will 288 be used. 289 This can be a <link linkend="libpq-connstring">connection 290 string</link>. If so, connection string parameters will override any 291 conflicting command line options. 292 </para> 293 </listitem> 294 </varlistentry> 295 </variablelist> 296 </para> 297 298 </refsect1> 299 300 301 <refsect1> 302 <title>Environment</title> 303 304 <variablelist> 305 <varlistentry> 306 <term><envar>PGDATABASE</envar></term> 307 <listitem> 308 <para> 309 If set, the name of the database to create, unless overridden on 310 the command line. 311 </para> 312 </listitem> 313 </varlistentry> 314 315 <varlistentry> 316 <term><envar>PGHOST</envar></term> 317 <term><envar>PGPORT</envar></term> 318 <term><envar>PGUSER</envar></term> 319 320 <listitem> 321 <para> 322 Default connection parameters. <envar>PGUSER</envar> also 323 determines the name of the database to create, if it is not 324 specified on the command line or by <envar>PGDATABASE</envar>. 325 </para> 326 </listitem> 327 </varlistentry> 328 </variablelist> 329 330 <para> 331 This utility, like most other <productname>PostgreSQL</> utilities, 332 also uses the environment variables supported by <application>libpq</> 333 (see <xref linkend="libpq-envars">). 334 </para> 335 336 </refsect1> 337 338 339 <refsect1> 340 <title>Diagnostics</title> 341 342 <para> 343 In case of difficulty, see <xref linkend="SQL-CREATEDATABASE"> 344 and <xref linkend="APP-PSQL"> for 345 discussions of potential problems and error messages. 346 The database server must be running at the 347 targeted host. Also, any default connection settings and environment 348 variables used by the <application>libpq</application> front-end 349 library will apply. 350 </para> 351 352 </refsect1> 353 354 355 <refsect1> 356 <title>Examples</title> 357 358 <para> 359 To create the database <literal>demo</literal> using the default 360 database server: 361<screen> 362<prompt>$ </prompt><userinput>createdb demo</userinput> 363</screen> 364 </para> 365 366 <para> 367 To create the database <literal>demo</literal> using the 368 server on host <literal>eden</>, port 5000, using the 369 <literal>template0</literal> template database, here is the 370 command-line command and the underlying SQL command: 371<screen> 372<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput> 373<computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput> 374</screen></para> 375 </refsect1> 376 377 378 <refsect1> 379 <title>See Also</title> 380 381 <simplelist type="inline"> 382 <member><xref linkend="app-dropdb"></member> 383 <member><xref linkend="sql-createdatabase"></member> 384 </simplelist> 385 </refsect1> 386 387</refentry> 388