← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to contrib/pg_dumplo/README.pg_dumplo

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
contrib/pg_dumplo/README.pg_dumplo
 
1
$PostgreSQL: pgsql/contrib/pg_dumplo/README.pg_dumplo,v 1.3 2003-11-29 19:51:35 pgsql Exp $
 
2
 
 
3
pg_dumplo - PostgreSQL large object dumper
 
4
==========================================        
 
5
 
 
6
By Karel Zak <zakkr@zf.jcu.cz>
 
7
 
 
8
 
 
9
Compilation:
 
10
===========
 
11
 
 
12
        * run master ./configure in the PG source top directory  
 
13
        * gmake all
 
14
        * gmake install
 
15
        
 
16
THANKS:
 
17
====== 
 
18
 
 
19
        <??? I lost his e-mail ???>
 
20
                * option '--all' and pg_class usage
 
21
 
 
22
        Pavel Jan�k ml. <Pavel.Janik@linux.cz>
 
23
                * HOWTO (the rest of this file)
 
24
 
 
25
 
 
26
How to use pg_dumplo?
 
27
=====================
 
28
 
 
29
(c) 2000, Pavel Jan�k ml. <Pavel.Janik@linux.cz>
 
30
 
 
31
 
 
32
Q: How do you use pg_dumplo?
 
33
============================
 
34
 
 
35
A: This is a small demo of backing up the database table with Large Objects:
 
36
 
 
37
 
 
38
We will create a demo database and a small and useless table `lo' inside
 
39
it:
 
40
 
 
41
SnowWhite:$ createdb test
 
42
CREATE DATABASE
 
43
 
 
44
Ok, our database with the name 'test' is created. Now we should create demo
 
45
table which will contain only one column with the name 'id' which will hold
 
46
the OID number of a Large Object:
 
47
 
 
48
SnowWhite:$ psql test
 
49
Welcome to psql, the PostgreSQL interactive terminal.
 
50
 
 
51
Type:  \copyright for distribution terms
 
52
       \h for help with SQL commands
 
53
       \? for help on internal slash commands
 
54
       \g or terminate with semicolon to execute query
 
55
       \q to quit
 
56
 
 
57
test=# CREATE TABLE lo (id oid);
 
58
CREATE
 
59
test=# \lo_import /etc/aliases
 
60
lo_import 19338
 
61
test=# INSERT INTO lo VALUES (19338);
 
62
INSERT 19352 1
 
63
test=# select * from lo;
 
64
  id   
 
65
-------
 
66
 19338
 
67
(1 row)
 
68
 
 
69
test=# \q
 
70
 
 
71
In the above example you can see that we have also imported one "Large
 
72
Object" - the file /etc/aliases. It has an oid of 19338 so we have inserted
 
73
this oid number to the database table lo to the column id. The final SELECT
 
74
shows that we have one record in the table.
 
75
 
 
76
Now we can demonstrate the work of pg_dumplo. We will create a dump directory
 
77
which will contain the whole dump of large objects (/tmp/dump):
 
78
 
 
79
mkdir -p /tmp/dump
 
80
 
 
81
Now we can dump all large objects from the database `test' which have OIDs
 
82
stored in the column `id' in the table `lo':
 
83
 
 
84
SnowWhite:$ pg_dumplo -s /tmp/dump -d test -l lo.id
 
85
pg_dumplo: dump lo.id (1 large obj)
 
86
 
 
87
Voila, we have the dump of all Large Objects in our directory:
 
88
 
 
89
SnowWhite:$ tree /tmp/dump/
 
90
/tmp/dump/
 
91
`-- test
 
92
    |-- lo
 
93
    |   `-- id
 
94
    |       `-- 19338
 
95
    `-- lo_dump.index
 
96
 
 
97
3 directories, 2 files
 
98
SnowWhite:$ 
 
99
 
 
100
In practice, we'd probably use
 
101
 
 
102
SnowWhite:$ pg_dumplo -s /tmp/dump -d test -e
 
103
 
 
104
to export all large objects that are referenced by any OID-type column
 
105
in the database.  Calling out specific column(s) with -l is only needed
 
106
for a selective dump.
 
107
 
 
108
For routine backup purposes, the dump directory could now be converted into
 
109
an archive file with tar and stored on tape.  Notice that a single dump
 
110
directory can hold the dump of multiple databases.
 
111
 
 
112
Now, how can we recreate the contents of the table lo and the Large Object
 
113
database when something went wrong?  To do this, we expect that pg_dump is
 
114
also used to store the definition and contents of the regular tables in
 
115
the database.
 
116
 
 
117
SnowWhite:$ pg_dump test >test.backup
 
118
 
 
119
Now, if we lose the database:
 
120
 
 
121
SnowWhite:$ dropdb test
 
122
DROP DATABASE
 
123
 
 
124
we can recreate it and reload the regular tables from the dump file:
 
125
 
 
126
SnowWhite:$ createdb test
 
127
CREATE DATABASE
 
128
 
 
129
SnowWhite:$ psql test <test.backup
 
130
 
 
131
But at this point our database has no large objects in it.  What's more,
 
132
the large-object-referencing columns contain the OIDs of the old large
 
133
objects, which will not be the OIDs they'll have when reloaded.  Never
 
134
fear: pg_dumplo will fix the large object references at the same time
 
135
it reloads the large objects.  We reload the LO data from the dump
 
136
directory like this:
 
137
 
 
138
SnowWhite:$ pg_dumplo -s /tmp/dump -d test -i
 
139
19338   lo      id      test/lo/id/19338
 
140
SnowWhite:$
 
141
 
 
142
And this is everything.  The contents of table lo will be automatically
 
143
updated to refer to the new large object OIDs.
 
144
 
 
145
Summary: In this small example we have shown that pg_dumplo can be used to
 
146
completely dump the database's Large Objects very easily.
 
147
 
 
148
For more information see the help ( pg_dumplo -h ).