I686LINUX/util/I686LINUX/doc/postgresql/html/sql-createdatabase.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >CREATE DATABASE</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="SQL Commands"
  16 HREF="sql-commands.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="CREATE CONVERSION"
  19 HREF="sql-createconversion.html"><LINK
  20 REL="NEXT"
  21 TITLE="CREATE DOMAIN"
  22 HREF="sql-createdomain.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="sql-createconversion.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="sql-createconversion.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="sql-createdomain.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="sql-createdomain.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><H1
  91 ><A
  92 NAME="SQL-CREATEDATABASE"
  93 ></A
  94 >CREATE DATABASE</H1
  95 ><DIV
  96 CLASS="REFNAMEDIV"
  97 ><A
  98 NAME="AEN36765"
  99 ></A
 100 ><H2
 101 >Name</H2
 102 >CREATE DATABASE&nbsp;--&nbsp;create a new database</DIV
 103 ><A
 104 NAME="AEN36768"
 105 ></A
 106 ><DIV
 107 CLASS="REFSYNOPSISDIV"
 108 ><A
 109 NAME="AEN36770"
 110 ></A
 111 ><H2
 112 >Synopsis</H2
 113 ><PRE
 114 CLASS="SYNOPSIS"
 115 >CREATE DATABASE <VAR
 116 CLASS="REPLACEABLE"
 117 >name</VAR
 118 >
 119     [ [ WITH ] [ OWNER [=] <VAR
 120 CLASS="REPLACEABLE"
 121 >dbowner</VAR
 122 > ]
 123            [ LOCATION [=] '<VAR
 124 CLASS="REPLACEABLE"
 125 >dbpath</VAR
 126 >' ]
 127            [ TEMPLATE [=] <VAR
 128 CLASS="REPLACEABLE"
 129 >template</VAR
 130 > ]
 131            [ ENCODING [=] <VAR
 132 CLASS="REPLACEABLE"
 133 >encoding</VAR
 134 > ] ]</PRE
 135 ></DIV
 136 ><DIV
 137 CLASS="REFSECT1"
 138 ><A
 139 NAME="AEN36777"
 140 ></A
 141 ><H2
 142 >Description</H2
 143 ><P
 144 >   <TT
 145 CLASS="COMMAND"
 146 >CREATE DATABASE</TT
 147 > creates a new
 148    <SPAN
 149 CLASS="PRODUCTNAME"
 150 >PostgreSQL</SPAN
 151 > database.
 152   </P
 153 ><P
 154 >   To create a database, you must be a superuser or have the special
 155    <TT
 156 CLASS="LITERAL"
 157 >CREATEDB</TT
 158 > privilege.
 159    See <A
 160 HREF="sql-createuser.html"
 161 ><I
 162 >CREATE USER</I
 163 ></A
 164 >.
 165   </P
 166 ><P
 167 >   Normally, the creator becomes the owner of the new database.
 168    Superusers can create databases owned by other users using the
 169    <TT
 170 CLASS="LITERAL"
 171 >OWNER</TT
 172 > clause. They can even create databases owned by
 173    users with no special privileges. Non-superusers with <TT
 174 CLASS="LITERAL"
 175 >CREATEDB</TT
 176 >
 177    privilege can only create databases owned by themselves.
 178   </P
 179 ><P
 180 >   An alternative location can be specified in order to,
 181    for example, store the database on a different disk.
 182    The path must have been prepared with the
 183    <A
 184 HREF="app-initlocation.html"
 185 ><I
 186 ><I
 187 >initlocation</I
 188 ></I
 189 ></A
 190 >
 191    command.
 192   </P
 193 ><P
 194 >   If the path name does not contain a slash, it is interpreted
 195    as an environment variable name, which must be known to the
 196    server process. This way the database administrator can
 197    exercise control over locations in which databases can be created.
 198    (A customary choice is, e.g., <TT
 199 CLASS="ENVAR"
 200 >PGDATA2</TT
 201 >.)
 202    If the server is compiled with <TT
 203 CLASS="LITERAL"
 204 >ALLOW_ABSOLUTE_DBPATHS</TT
 205 >
 206    (not so by default), absolute path names, as identified by
 207    a leading slash
 208    (e.g., <TT
 209 CLASS="FILENAME"
 210 >/usr/local/pgsql/data</TT
 211 >),
 212    are allowed as well.
 213    In either case, the final path name must be absolute and must not
 214    contain any single quotes.
 215   </P
 216 ><P
 217 >   By default, the new database will be created by cloning the standard
 218    system database <TT
 219 CLASS="LITERAL"
 220 >template1</TT
 221 >.  A different template can be
 222    specified by writing <TT
 223 CLASS="LITERAL"
 224 >TEMPLATE
 225    <VAR
 226 CLASS="REPLACEABLE"
 227 >name</VAR
 228 ></TT
 229 >.  In particular,
 230    by writing <TT
 231 CLASS="LITERAL"
 232 >TEMPLATE template0</TT
 233 >, you can create a virgin
 234    database containing only the standard objects predefined by your
 235    version of <SPAN
 236 CLASS="PRODUCTNAME"
 237 >PostgreSQL</SPAN
 238 >.  This is useful
 239    if you wish to avoid copying
 240    any installation-local objects that may have been added to
 241    <TT
 242 CLASS="LITERAL"
 243 >template1</TT
 244 >.
 245   </P
 246 ><P
 247 >   The optional encoding parameter allows selection of the database
 248    encoding.  When not specified, it defaults to the encoding used by
 249    the selected template database.
 250   </P
 251 ></DIV
 252 ><DIV
 253 CLASS="REFSECT1"
 254 ><A
 255 NAME="AEN36802"
 256 ></A
 257 ><H2
 258 >Parameters</H2
 259 ><P
 260 ></P
 261 ><DIV
 262 CLASS="VARIABLELIST"
 263 ><DL
 264 ><DT
 265 ><VAR
 266 CLASS="REPLACEABLE"
 267 >name</VAR
 268 ></DT
 269 ><DD
 270 ><P
 271 >       The name of a database to create.
 272        </P
 273 ></DD
 274 ><DT
 275 ><VAR
 276 CLASS="REPLACEABLE"
 277 >dbowner</VAR
 278 ></DT
 279 ><DD
 280 ><P
 281 >        The name of the database user who will own the new database,
 282         or <TT
 283 CLASS="LITERAL"
 284 >DEFAULT</TT
 285 > to use the default (namely, the
 286         user executing the command).
 287        </P
 288 ></DD
 289 ><DT
 290 ><VAR
 291 CLASS="REPLACEABLE"
 292 >dbpath</VAR
 293 ></DT
 294 ><DD
 295 ><P
 296 >       An alternate file-system location in which to store the new database,
 297         specified as a string literal;
 298         or <TT
 299 CLASS="LITERAL"
 300 >DEFAULT</TT
 301 > to use the default location.
 302        </P
 303 ></DD
 304 ><DT
 305 ><VAR
 306 CLASS="REPLACEABLE"
 307 >template</VAR
 308 ></DT
 309 ><DD
 310 ><P
 311 >        The name of the template from which to create the new database,
 312         or <TT
 313 CLASS="LITERAL"
 314 >DEFAULT</TT
 315 > to use the default template
 316         (<TT
 317 CLASS="LITERAL"
 318 >template1</TT
 319 >).
 320        </P
 321 ></DD
 322 ><DT
 323 ><VAR
 324 CLASS="REPLACEABLE"
 325 >encoding</VAR
 326 ></DT
 327 ><DD
 328 ><P
 329 >        Character set encoding to use in the new database.  Specify
 330         a string constant (e.g., <TT
 331 CLASS="LITERAL"
 332 >'SQL_ASCII'</TT
 333 >),
 334         or an integer encoding number, or <TT
 335 CLASS="LITERAL"
 336 >DEFAULT</TT
 337 >
 338         to use the default encoding.
 339        </P
 340 ></DD
 341 ></DL
 342 ></DIV
 343 ><P
 344 >   Optional parameters can be written in any order, not only the order
 345    illustrated above.
 346   </P
 347 ></DIV
 348 ><DIV
 349 CLASS="REFSECT1"
 350 ><A
 351 NAME="AEN36837"
 352 ></A
 353 ><H2
 354 >Notes</H2
 355 ><P
 356 >    <TT
 357 CLASS="COMMAND"
 358 >CREATE DATABASE</TT
 359 > cannot be executed inside a transaction
 360     block.
 361    </P
 362 ><P
 363 >    Errors along the line of <SPAN
 364 CLASS="QUOTE"
 365 >"could not initialize database directory"</SPAN
 366 >
 367     are most likely related to insufficient permissions on the data
 368     directory, a full disk, or other file system problems.  When using an
 369     alternate location, the user under
 370     which the database server is running must have access to the location.
 371    </P
 372 ><P
 373 >    Use <A
 374 HREF="sql-dropdatabase.html"
 375 ><I
 376 >DROP DATABASE</I
 377 ></A
 378 > to remove a database.
 379    </P
 380 ><P
 381 >    The program <A
 382 HREF="app-createdb.html"
 383 ><I
 384 ><I
 385 >createdb</I
 386 ></I
 387 ></A
 388 > is a
 389     wrapper program around this command, provided for convenience.
 390    </P
 391 ><P
 392 >   There are security issues involved with using alternate database
 393    locations specified with absolute path names; this is why the feature
 394    is not enabled by default.  See <A
 395 HREF="manage-ag-alternate-locs.html"
 396 >Section 18.5</A
 397 > for more information.
 398   </P
 399 ><P
 400 >   Although it is possible to copy a database other than <TT
 401 CLASS="LITERAL"
 402 >template1</TT
 403 >
 404    by specifying its name as the template, this is not (yet) intended as
 405    a general-purpose <SPAN
 406 CLASS="QUOTE"
 407 >"<TT
 408 CLASS="COMMAND"
 409 >COPY DATABASE</TT
 410 >"</SPAN
 411 > facility.
 412    We recommend that databases used as templates be treated as read-only.
 413    See <A
 414 HREF="manage-ag-templatedbs.html"
 415 >Section 18.3</A
 416 > for more information.
 417   </P
 418 ></DIV
 419 ><DIV
 420 CLASS="REFSECT1"
 421 ><A
 422 NAME="AEN36854"
 423 ></A
 424 ><H2
 425 >Examples</H2
 426 ><P
 427 >   To create a new database:
 428
 429 </P><PRE
 430 CLASS="PROGRAMLISTING"
 431 >CREATE DATABASE lusiadas;</PRE
 432 ><P>
 433   </P
 434 ><P
 435 >   To create a new database in an alternate area
 436    <TT
 437 CLASS="FILENAME"
 438 >~/private_db</TT
 439 >, execute the following from the
 440    shell:
 441
 442 </P><PRE
 443 CLASS="PROGRAMLISTING"
 444 >mkdir private_db
 445 initlocation ~/private_db</PRE
 446 ><P>
 447
 448    Then execute the following from within a
 449    <SPAN
 450 CLASS="APPLICATION"
 451 >psql</SPAN
 452 > session:
 453
 454 </P><PRE
 455 CLASS="PROGRAMLISTING"
 456 >CREATE DATABASE elsewhere WITH LOCATION '/home/olly/private_db';</PRE
 457 ><P>
 458   </P
 459 ></DIV
 460 ><DIV
 461 CLASS="REFSECT1"
 462 ><A
 463 NAME="AEN36863"
 464 ></A
 465 ><H2
 466 >Compatibility</H2
 467 ><P
 468 >   There is no <TT
 469 CLASS="COMMAND"
 470 >CREATE DATABASE</TT
 471 > statement in the SQL
 472    standard.  Databases are equivalent to catalogs, whose creation is
 473    implementation-defined.
 474   </P
 475 ></DIV
 476 ><DIV
 477 CLASS="NAVFOOTER"
 478 ><HR
 479 ALIGN="LEFT"
 480 WIDTH="100%"><TABLE
 481 SUMMARY="Footer navigation table"
 482 WIDTH="100%"
 483 BORDER="0"
 484 CELLPADDING="0"
 485 CELLSPACING="0"
 486 ><TR
 487 ><TD
 488 WIDTH="33%"
 489 ALIGN="left"
 490 VALIGN="top"
 491 ><A
 492 HREF="sql-createconversion.html"
 493 ACCESSKEY="P"
 494 >Prev</A
 495 ></TD
 496 ><TD
 497 WIDTH="34%"
 498 ALIGN="center"
 499 VALIGN="top"
 500 ><A
 501 HREF="index.html"
 502 ACCESSKEY="H"
 503 >Home</A
 504 ></TD
 505 ><TD
 506 WIDTH="33%"
 507 ALIGN="right"
 508 VALIGN="top"
 509 ><A
 510 HREF="sql-createdomain.html"
 511 ACCESSKEY="N"
 512 >Next</A
 513 ></TD
 514 ></TR
 515 ><TR
 516 ><TD
 517 WIDTH="33%"
 518 ALIGN="left"
 519 VALIGN="top"
 520 >CREATE CONVERSION</TD
 521 ><TD
 522 WIDTH="34%"
 523 ALIGN="center"
 524 VALIGN="top"
 525 ><A
 526 HREF="sql-commands.html"
 527 ACCESSKEY="U"
 528 >Up</A
 529 ></TD
 530 ><TD
 531 WIDTH="33%"
 532 ALIGN="right"
 533 VALIGN="top"
 534 >CREATE DOMAIN</TD
 535 ></TR
 536 ></TABLE
 537 ></DIV
 538 ></BODY
 539 ></HTML
 540 >