postgresql/doc/src/sgml/vacuumlo.sgml

<!-- doc/src/sgml/vacuumlo.sgml -->

<sect1 id="vacuumlo" xreflabel="vacuumlo">
 <title>vacuumlo</title>

 <indexterm zone="vacuumlo">
  <primary>vacuumlo</primary>
 </indexterm>

 <para>
  <application>vacuumlo</> is a simple utility program that will remove any
  <quote>orphaned</> large objects from a
  <productname>PostgreSQL</> database.  An orphaned large object (LO) is
  considered to be any LO whose OID does not appear in any <type>oid</> or
  <type>lo</> data column of the database.
 </para>

 <para>
  If you use this, you may also be interested in the <function>lo_manage</>
  trigger in the <xref linkend="lo"> module.
  <function>lo_manage</> is useful to try
  to avoid creating orphaned LOs in the first place.
 </para>

 <sect2>
  <title>Usage</title>

<synopsis>
vacuumlo [options] database [database2 ... databaseN]
</synopsis>

  <para>
   All databases named on the command line are processed.  Available options
   include:
  </para>

  <variablelist>
   <varlistentry>
    <term><option>-v</option></term>
    <listitem>
     <para>Write a lot of progress messages.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-n</option></term>
    <listitem>
     <para>Don't remove anything, just show what would be done.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-l</option> <replaceable>limit</></term>
    <listitem>
     <para>
      Remove no more than <replaceable>limit</> large objects per
      transaction (default 1000).  Since the server acquires a lock per LO
      removed, removing too many LOs in one transaction risks exceeding
      <xref linkend="guc-max-locks-per-transaction">.  Set the limit to
      zero if you want all removals done in a single transaction.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-U</option> <replaceable>username</></term>
    <listitem>
     <para>User name to connect as.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-w</></term>
    <term><option>--no-password</></term>
    <listitem>
     <para>
      Never issue a password prompt.  If the server requires password
      authentication and a password is not available by other means
      such as a <filename>.pgpass</filename> file, the connection
      attempt will fail.  This option can be useful in batch jobs and
      scripts where no user is present to enter a password.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-W</option></term>
    <listitem>
     <para>
      Force <application>vacuumlo</application> to prompt for a
      password before connecting to a database.
     </para>

     <para>
      This option is never essential, since
      <application>vacuumlo</application> will automatically prompt
      for a password if the server demands password authentication.
      However, <application>vacuumlo</application> will waste a
      connection attempt finding out that the server wants a password.
      In some cases it is worth typing <option>-W</> to avoid the extra
      connection attempt.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-h</option> <replaceable>hostname</></term>
    <listitem>
     <para>Database server's host.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-p</option> <replaceable>port</></term>
    <listitem>
     <para>Database server's port.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2>
  <title>Method</title>

  <para>
   First, <application>vacuumlo</> builds a temporary table which contains all
   of the OIDs of the large objects in the selected database.
  </para>

  <para>
   It then scans through all columns in the database that are of type
   <type>oid</> or <type>lo</>, and removes matching entries from the
   temporary table.  (Note: only types with these names are considered;
   in particular, domains over them are not considered.)
  </para>

  <para>
   The remaining entries in the temporary table identify orphaned LOs.
   These are removed.
  </para>
 </sect2>

 <sect2>
  <title>Author</title>

  <para>
   Peter Mount <email>peter@retep.org.uk</email>
  </para>
 </sect2>

</sect1>