← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/manage-ag-templatedbs.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/manage-ag-templatedbs.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Template Databases</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Managing Databases"
 
16
HREF="managing-databases.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Creating a Database"
 
19
HREF="manage-ag-createdb.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Database Configuration"
 
22
HREF="manage-ag-config.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Creating a Database"
 
57
HREF="manage-ag-createdb.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="Managing Databases"
 
67
HREF="managing-databases.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 21. Managing Databases</TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Managing Databases"
 
81
HREF="managing-databases.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="Database Configuration"
 
90
HREF="manage-ag-config.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="SECT1"
 
101
><H1
 
102
CLASS="SECT1"
 
103
><A
 
104
NAME="MANAGE-AG-TEMPLATEDBS"
 
105
>21.3. Template Databases</A
 
106
></H1
 
107
><P
 
108
>   <TT
 
109
CLASS="COMMAND"
 
110
>CREATE DATABASE</TT
 
111
> actually works by copying an existing
 
112
   database.  By default, it copies the standard system database named
 
113
   <TT
 
114
CLASS="LITERAL"
 
115
>template1</TT
 
116
>. Thus that
 
117
   database is the <SPAN
 
118
CLASS="QUOTE"
 
119
>"template"</SPAN
 
120
> from which new databases are
 
121
   made.  If you add objects to <TT
 
122
CLASS="LITERAL"
 
123
>template1</TT
 
124
>, these objects
 
125
   will be copied into subsequently created user databases.  This
 
126
   behavior allows site-local modifications to the standard set of
 
127
   objects in databases.  For example, if you install the procedural
 
128
   language <SPAN
 
129
CLASS="APPLICATION"
 
130
>PL/Perl</SPAN
 
131
> in <TT
 
132
CLASS="LITERAL"
 
133
>template1</TT
 
134
>, it will
 
135
   automatically be available in user databases without any extra
 
136
   action being taken when those databases are created.
 
137
  </P
 
138
><P
 
139
>   There is a second standard system database named
 
140
   <TT
 
141
CLASS="LITERAL"
 
142
>template0</TT
 
143
>. This
 
144
   database contains the same data as the initial contents of
 
145
   <TT
 
146
CLASS="LITERAL"
 
147
>template1</TT
 
148
>, that is, only the standard objects
 
149
   predefined by your version of
 
150
   <SPAN
 
151
CLASS="PRODUCTNAME"
 
152
>PostgreSQL</SPAN
 
153
>.  <TT
 
154
CLASS="LITERAL"
 
155
>template0</TT
 
156
>
 
157
   should never be changed after the database cluster has been
 
158
   initialized.  By instructing
 
159
   <TT
 
160
CLASS="COMMAND"
 
161
>CREATE DATABASE</TT
 
162
> to copy <TT
 
163
CLASS="LITERAL"
 
164
>template0</TT
 
165
> instead
 
166
   of <TT
 
167
CLASS="LITERAL"
 
168
>template1</TT
 
169
>, you can create a <SPAN
 
170
CLASS="QUOTE"
 
171
>"virgin"</SPAN
 
172
> user
 
173
   database that contains none of the site-local additions in
 
174
   <TT
 
175
CLASS="LITERAL"
 
176
>template1</TT
 
177
>.  This is particularly handy when restoring a
 
178
   <TT
 
179
CLASS="LITERAL"
 
180
>pg_dump</TT
 
181
> dump: the dump script should be restored in a
 
182
   virgin database to ensure that one recreates the correct contents
 
183
   of the dumped database, without conflicting with objects that
 
184
   might have been added to <TT
 
185
CLASS="LITERAL"
 
186
>template1</TT
 
187
> later on.
 
188
  </P
 
189
><P
 
190
>   Another common reason for copying <TT
 
191
CLASS="LITERAL"
 
192
>template0</TT
 
193
> instead
 
194
   of <TT
 
195
CLASS="LITERAL"
 
196
>template1</TT
 
197
> is that new encoding and locale settings
 
198
   can be specified when copying <TT
 
199
CLASS="LITERAL"
 
200
>template0</TT
 
201
>, whereas a copy
 
202
   of <TT
 
203
CLASS="LITERAL"
 
204
>template1</TT
 
205
> must use the same settings it does.
 
206
   This is because <TT
 
207
CLASS="LITERAL"
 
208
>template1</TT
 
209
> might contain encoding-specific
 
210
   or locale-specific data, while <TT
 
211
CLASS="LITERAL"
 
212
>template0</TT
 
213
> is known not to.
 
214
  </P
 
215
><P
 
216
>   To create a database by copying <TT
 
217
CLASS="LITERAL"
 
218
>template0</TT
 
219
>, use:
 
220
</P><PRE
 
221
CLASS="PROGRAMLISTING"
 
222
>CREATE DATABASE <TT
 
223
CLASS="REPLACEABLE"
 
224
><I
 
225
>dbname</I
 
226
></TT
 
227
> TEMPLATE template0;</PRE
 
228
><P>
 
229
   from the SQL environment, or:
 
230
</P><PRE
 
231
CLASS="PROGRAMLISTING"
 
232
>createdb -T template0 <TT
 
233
CLASS="REPLACEABLE"
 
234
><I
 
235
>dbname</I
 
236
></TT
 
237
></PRE
 
238
><P>
 
239
   from the shell.
 
240
  </P
 
241
><P
 
242
>   It is possible to create additional template databases, and indeed
 
243
   one can copy any database in a cluster by specifying its name
 
244
   as the template for <TT
 
245
CLASS="COMMAND"
 
246
>CREATE DATABASE</TT
 
247
>.  It is important to
 
248
   understand, however, that this is not (yet) intended as
 
249
   a general-purpose <SPAN
 
250
CLASS="QUOTE"
 
251
>"<TT
 
252
CLASS="COMMAND"
 
253
>COPY DATABASE</TT
 
254
>"</SPAN
 
255
> facility.
 
256
   The principal limitation is that no other sessions can be connected to
 
257
   the source database while it is being copied.  <TT
 
258
CLASS="COMMAND"
 
259
>CREATE
 
260
   DATABASE</TT
 
261
> will fail if any other connection exists when it starts;
 
262
   during the copy operation, new connections to the source database
 
263
   are prevented.
 
264
  </P
 
265
><P
 
266
>   Two useful flags exist in <TT
 
267
CLASS="LITERAL"
 
268
>pg_database</TT
 
269
> for each
 
270
   database: the columns <TT
 
271
CLASS="LITERAL"
 
272
>datistemplate</TT
 
273
> and
 
274
   <TT
 
275
CLASS="LITERAL"
 
276
>datallowconn</TT
 
277
>.  <TT
 
278
CLASS="LITERAL"
 
279
>datistemplate</TT
 
280
>
 
281
   can be set to indicate that a database is intended as a template for
 
282
   <TT
 
283
CLASS="COMMAND"
 
284
>CREATE DATABASE</TT
 
285
>.  If this flag is set, the database can be
 
286
   cloned by any user with <TT
 
287
CLASS="LITERAL"
 
288
>CREATEDB</TT
 
289
> privileges; if it is not set,
 
290
   only superusers and the owner of the database can clone it.
 
291
   If <TT
 
292
CLASS="LITERAL"
 
293
>datallowconn</TT
 
294
> is false, then no new connections
 
295
   to that database will be allowed (but existing sessions are not terminated
 
296
   simply by setting the flag false).  The <TT
 
297
CLASS="LITERAL"
 
298
>template0</TT
 
299
>
 
300
   database is normally marked <TT
 
301
CLASS="LITERAL"
 
302
>datallowconn = false</TT
 
303
> to prevent its modification.
 
304
   Both <TT
 
305
CLASS="LITERAL"
 
306
>template0</TT
 
307
> and <TT
 
308
CLASS="LITERAL"
 
309
>template1</TT
 
310
>
 
311
   should always be marked with <TT
 
312
CLASS="LITERAL"
 
313
>datistemplate = true</TT
 
314
>.
 
315
  </P
 
316
><DIV
 
317
CLASS="NOTE"
 
318
><BLOCKQUOTE
 
319
CLASS="NOTE"
 
320
><P
 
321
><B
 
322
>Note: </B
 
323
>    <TT
 
324
CLASS="LITERAL"
 
325
>template1</TT
 
326
> and <TT
 
327
CLASS="LITERAL"
 
328
>template0</TT
 
329
> do not have any special
 
330
    status beyond the fact that the name <TT
 
331
CLASS="LITERAL"
 
332
>template1</TT
 
333
> is the default
 
334
    source database name for <TT
 
335
CLASS="COMMAND"
 
336
>CREATE DATABASE</TT
 
337
>.
 
338
    For example, one could drop <TT
 
339
CLASS="LITERAL"
 
340
>template1</TT
 
341
> and recreate it from
 
342
    <TT
 
343
CLASS="LITERAL"
 
344
>template0</TT
 
345
> without any ill effects.  This course of action
 
346
    might be advisable if one has carelessly added a bunch of junk in
 
347
    <TT
 
348
CLASS="LITERAL"
 
349
>template1</TT
 
350
>. (To delete <TT
 
351
CLASS="LITERAL"
 
352
>template1</TT
 
353
>,
 
354
    it must have <TT
 
355
CLASS="LITERAL"
 
356
>pg_database.datistemplate = false</TT
 
357
>.)
 
358
   </P
 
359
><P
 
360
>    The <TT
 
361
CLASS="LITERAL"
 
362
>postgres</TT
 
363
> database is also created when a database
 
364
    cluster is initialized.  This database is meant as a default database for
 
365
    users and applications to connect to. It is simply a copy of
 
366
    <TT
 
367
CLASS="LITERAL"
 
368
>template1</TT
 
369
> and can be dropped and recreated if necessary.
 
370
   </P
 
371
></BLOCKQUOTE
 
372
></DIV
 
373
></DIV
 
374
><DIV
 
375
CLASS="NAVFOOTER"
 
376
><HR
 
377
ALIGN="LEFT"
 
378
WIDTH="100%"><TABLE
 
379
SUMMARY="Footer navigation table"
 
380
WIDTH="100%"
 
381
BORDER="0"
 
382
CELLPADDING="0"
 
383
CELLSPACING="0"
 
384
><TR
 
385
><TD
 
386
WIDTH="33%"
 
387
ALIGN="left"
 
388
VALIGN="top"
 
389
><A
 
390
HREF="manage-ag-createdb.html"
 
391
ACCESSKEY="P"
 
392
>Prev</A
 
393
></TD
 
394
><TD
 
395
WIDTH="34%"
 
396
ALIGN="center"
 
397
VALIGN="top"
 
398
><A
 
399
HREF="index.html"
 
400
ACCESSKEY="H"
 
401
>Home</A
 
402
></TD
 
403
><TD
 
404
WIDTH="33%"
 
405
ALIGN="right"
 
406
VALIGN="top"
 
407
><A
 
408
HREF="manage-ag-config.html"
 
409
ACCESSKEY="N"
 
410
>Next</A
 
411
></TD
 
412
></TR
 
413
><TR
 
414
><TD
 
415
WIDTH="33%"
 
416
ALIGN="left"
 
417
VALIGN="top"
 
418
>Creating a Database</TD
 
419
><TD
 
420
WIDTH="34%"
 
421
ALIGN="center"
 
422
VALIGN="top"
 
423
><A
 
424
HREF="managing-databases.html"
 
425
ACCESSKEY="U"
 
426
>Up</A
 
427
></TD
 
428
><TD
 
429
WIDTH="33%"
 
430
ALIGN="right"
 
431
VALIGN="top"
 
432
>Database Configuration</TD
 
433
></TR
 
434
></TABLE
 
435
></DIV
 
436
></BODY
 
437
></HTML
 
438
>
 
 
b'\\ No newline at end of file'