1<!-- doc/src/sgml/vacuumlo.sgml -->
2
3<refentry id="vacuumlo">
4 <indexterm zone="vacuumlo">
5  <primary>vacuumlo</primary>
6 </indexterm>
7
8 <refmeta>
9  <refentrytitle><application>vacuumlo</application></refentrytitle>
10  <manvolnum>1</manvolnum>
11  <refmiscinfo>Application</refmiscinfo>
12 </refmeta>
13
14 <refnamediv>
15  <refname>vacuumlo</refname>
16  <refpurpose>remove orphaned large objects from a <productname>PostgreSQL</productname> database</refpurpose>
17 </refnamediv>
18
19 <refsynopsisdiv>
20  <cmdsynopsis>
21   <command>vacuumlo</command>
22   <arg choice="opt" rep="repeat"><replaceable>option</replaceable></arg>
23   <arg choice="plain" rep="repeat"><replaceable>dbname</replaceable></arg>
24  </cmdsynopsis>
25 </refsynopsisdiv>
26
27 <refsect1>
28  <title>Description</title>
29
30 <para>
31  <application>vacuumlo</application> is a simple utility program that will remove any
32  <quote>orphaned</quote> large objects from a
33  <productname>PostgreSQL</productname> database.  An orphaned large object (LO) is
34  considered to be any LO whose OID does not appear in any <type>oid</type> or
35  <type>lo</type> data column of the database.
36 </para>
37
38 <para>
39  If you use this, you may also be interested in the <function>lo_manage</function>
40  trigger in the <xref linkend="lo"/> module.
41  <function>lo_manage</function> is useful to try
42  to avoid creating orphaned LOs in the first place.
43 </para>
44
45  <para>
46   All databases named on the command line are processed.
47  </para>
48 </refsect1>
49
50 <refsect1>
51  <title>Options</title>
52
53  <para>
54   <application>vacuumlo</application> accepts the following command-line arguments:
55
56  <variablelist>
57   <varlistentry>
58    <term><option>-l <replaceable class="parameter">limit</replaceable></option></term>
59    <term><option>--limit=<replaceable class="parameter">limit</replaceable></option></term>
60    <listitem>
61     <para>
62      Remove no more than <replaceable>limit</replaceable> large objects per
63      transaction (default 1000).  Since the server acquires a lock per LO
64      removed, removing too many LOs in one transaction risks exceeding
65      <xref linkend="guc-max-locks-per-transaction"/>.  Set the limit to
66      zero if you want all removals done in a single transaction.
67     </para>
68    </listitem>
69   </varlistentry>
70
71   <varlistentry>
72    <term><option>-n</option></term>
73    <term><option>--dry-run</option></term>
74    <listitem>
75     <para>Don't remove anything, just show what would be done.</para>
76    </listitem>
77   </varlistentry>
78
79   <varlistentry>
80    <term><option>-v</option></term>
81    <term><option>--verbose</option></term>
82    <listitem>
83     <para>Write a lot of progress messages.</para>
84    </listitem>
85   </varlistentry>
86
87   <varlistentry>
88    <term><option>-V</option></term>
89    <term><option>--version</option></term>
90    <listitem>
91     <para>
92      Print the <application>vacuumlo</application> version and exit.
93     </para>
94    </listitem>
95   </varlistentry>
96
97   <varlistentry>
98    <term><option>-?</option></term>
99    <term><option>--help</option></term>
100    <listitem>
101     <para>
102      Show help about <application>vacuumlo</application> command line
103      arguments, and exit.
104     </para>
105    </listitem>
106   </varlistentry>
107  </variablelist>
108  </para>
109
110  <para>
111   <application>vacuumlo</application> also accepts the following command-line
112   arguments for connection parameters:
113
114  <variablelist>
115   <varlistentry>
116    <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
117    <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
118    <listitem>
119     <para>Database server's host.</para>
120    </listitem>
121   </varlistentry>
122
123   <varlistentry>
124    <term><option>-p <replaceable>port</replaceable></option></term>
125    <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
126    <listitem>
127     <para>Database server's port.</para>
128    </listitem>
129   </varlistentry>
130
131   <varlistentry>
132    <term><option>-U <replaceable>username</replaceable></option></term>
133    <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
134    <listitem>
135     <para>User name to connect as.</para>
136    </listitem>
137   </varlistentry>
138
139   <varlistentry>
140    <term><option>-w</option></term>
141    <term><option>--no-password</option></term>
142    <listitem>
143     <para>
144      Never issue a password prompt.  If the server requires password
145      authentication and a password is not available by other means
146      such as a <filename>.pgpass</filename> file, the connection
147      attempt will fail.  This option can be useful in batch jobs and
148      scripts where no user is present to enter a password.
149     </para>
150    </listitem>
151   </varlistentry>
152
153   <varlistentry>
154    <term><option>-W</option></term>
155    <term><option>--password</option></term>
156    <listitem>
157     <para>
158      Force <application>vacuumlo</application> to prompt for a
159      password before connecting to a database.
160     </para>
161
162     <para>
163      This option is never essential, since
164      <application>vacuumlo</application> will automatically prompt
165      for a password if the server demands password authentication.
166      However, <application>vacuumlo</application> will waste a
167      connection attempt finding out that the server wants a password.
168      In some cases it is worth typing <option>-W</option> to avoid the extra
169      connection attempt.
170     </para>
171    </listitem>
172   </varlistentry>
173  </variablelist>
174  </para>
175 </refsect1>
176
177 <refsect1>
178  <title>Environment</title>
179
180  <variablelist>
181   <varlistentry>
182    <term><envar>PGHOST</envar></term>
183    <term><envar>PGPORT</envar></term>
184    <term><envar>PGUSER</envar></term>
185
186    <listitem>
187     <para>
188      Default connection parameters.
189     </para>
190    </listitem>
191   </varlistentry>
192  </variablelist>
193
194  <para>
195   This utility, like most other <productname>PostgreSQL</productname> utilities,
196   also uses the environment variables supported by <application>libpq</application>
197   (see <xref linkend="libpq-envars"/>).
198  </para>
199
200  <para>
201   The environment variable <envar>PG_COLOR</envar> specifies whether to use
202   color in diagnostic messages. Possible values are
203   <literal>always</literal>, <literal>auto</literal> and
204   <literal>never</literal>.
205  </para>
206 </refsect1>
207
208 <refsect1>
209  <title>Notes</title>
210
211  <para>
212   <application>vacuumlo</application> works by the following method:
213   First, <application>vacuumlo</application> builds a temporary table which contains all
214   of the OIDs of the large objects in the selected database.  It then scans
215   through all columns in the database that are of type
216   <type>oid</type> or <type>lo</type>, and removes matching entries from the temporary
217   table.  (Note: Only types with these names are considered; in particular,
218   domains over them are not considered.)  The remaining entries in the
219   temporary table identify orphaned LOs.  These are removed.
220  </para>
221 </refsect1>
222
223 <refsect1>
224  <title>Author</title>
225
226  <para>
227   Peter Mount <email>peter@retep.org.uk</email>
228  </para>
229 </refsect1>
230
231</refentry>
232