doc/src/sgml/vacuumlo.sgml

   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>