psql-ref.sgml

PostgreSQL7.4.6 for Linux

	alter table</userinput>.
	</para>
	</note>	
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\H</literal></term>
        <listitem>
        <para>
	Turns on <acronym>HTML</acronym> query output format. If the
	<acronym>HTML</acronym> format is already on, it is switched
	back to the default aligned text format. This command is for
	compatibility and convenience, but see <command>\pset</command>
	about setting other output options.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
        <listitem>
        <para>
        Reads input from the file <replaceable
        class="parameter">filename</replaceable> and executes it as
        though it had been typed on the keyboard.
        </para>
	<note>
	<para>
	If you want to see the lines on the screen as they are read you
	must set the variable <varname>ECHO</varname> to
	<literal>all</literal>.
	</para>
	</note>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\l</literal> (or <literal>\list</literal>)</term>
        <listitem>
        <para>
        List the names, owners, and character set encodings of all the databases in
        the server.  Append a <literal>+</literal> to the command name to
        see any descriptions for the databases as well.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>

	<listitem>
	<para>
	Reads the large object with <acronym>OID</acronym> <replaceable
	class="parameter">loid</replaceable> from the database and
	writes it to <replaceable
	class="parameter">filename</replaceable>. Note that this is
	subtly different from the server function
	<function>lo_export</function>, which acts with the permissions
	of the user that the database server runs as and on the server's
	file system.
	</para>
	<tip>
	<para>
	Use <command>\lo_list</command> to find out the large object's
	<acronym>OID</acronym>.
	</para>
	</tip>
	</listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>

	<listitem>
	<para>
	Stores the file into a <productname>PostgreSQL</productname>
	large object. Optionally, it associates the given
	comment with the object. Example:
<programlisting>
foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
lo_import 152801
</programlisting>
	The response indicates that the large object received object ID
	152801 which one ought to remember if one wants to access the
	object ever again. For that reason it is recommended to always
	associate a human-readable comment with every object. Those can
	then be seen with the <command>\lo_list</command> command.
	</para>

	<para>
	Note that this command is subtly different from the server-side
	<function>lo_import</function> because it acts as the local user
	on the local file system, rather than the server's user and file
	system.
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\lo_list</literal></term>
	<listitem>
	<para>
	Shows a list of all <productname>PostgreSQL</productname>
	large objects currently stored in the database,
	along with any comments provided for them.
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>

	<listitem>
	<para>
	Deletes the large object with <acronym>OID</acronym>
	<replaceable class="parameter">loid</replaceable> from the
	database.
	</para>

	<tip>
	<para>
	Use <command>\lo_list</command> to find out the large object's
	<acronym>OID</acronym>.
	</para>
	</tip>
	</listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>

        <listitem>
        <para>
        Saves future query results to the file <replaceable
        class="parameter">filename</replaceable> or pipes future results
        into a separate Unix shell to execute <replaceable
        class="parameter">command</replaceable>. If no arguments are
        specified, the query output will be reset to the standard output.
        </para>

	<para>
	<quote>Query results</quote> includes all tables, command
	responses, and notices obtained from the database server, as
	well as output of various backslash commands that query the
	database (such as <command>\d</command>), but not error
	messages.
	</para>

	<tip>
	<para>
	To intersperse text output in between query results, use
	<command>\qecho</command>.
	</para>
	</tip>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\p</literal></term>
        <listitem>
        <para>
        Print the current query buffer to the standard output.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>

	<listitem>
	<para>
	This command sets options affecting the output of query result
	tables. <replaceable class="parameter">parameter</replaceable>
	describes which option is to be set. The semantics of
	<replaceable class="parameter">value</replaceable> depend
	thereon.
	</para>

	<para>
	Adjustable printing options are:
	<variablelist>
	  <varlistentry>
	  <term><literal>format</literal></term>
	  <listitem>
	  <para>
	  Sets the output format to one of <literal>unaligned</literal>,
	  <literal>aligned</literal>, <literal>html</literal>, or
	  <literal>latex</literal>. Unique abbreviations are allowed.
	  (That would mean one letter is enough.)
	  </para>

	  <para>
	  <quote>Unaligned</quote> writes all columns of a row on a
	  line, separated by the currently active field separator. This
	  is intended to create output that might be intended to be read
	  in by other programs (tab-separated, comma-separated).
	  <quote>Aligned</quote> mode is the standard, human-readable,
	  nicely formatted text output that is default. The
	  <quote><acronym>HTML</acronym></quote> and
	  <quote>LaTeX</quote> modes put out tables that are intended to
	  be included in documents using the respective mark-up
	  language. They are not complete documents! (This might not be
	  so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
	  have a complete document wrapper.)
	  </para>
	  </listitem>
          </varlistentry>

	  <varlistentry>
	  <term><literal>border</literal></term>
	  <listitem>
	  <para>
	  The second argument must be a number. In general, the higher
	  the number the more borders and lines the tables will have,
	  but this depends on the particular format. In
	  <acronym>HTML</acronym> mode, this will translate directly
	  into the <literal>border=...</literal> attribute, in the
	  others only values 0 (no border), 1 (internal dividing lines),
	  and 2 (table frame) make sense.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>expanded</literal> (or <literal>x</literal>)</term>
	  <listitem>
	  <para>
	  Toggles between regular and expanded format. When expanded
	  format is enabled, all output has two columns with the column
	  name on the left and the data on the right. This mode is
	  useful if the data wouldn't fit on the screen in the normal
	  <quote>horizontal</quote> mode.
	  </para>

	  <para>
	  Expanded mode is supported by all four output formats.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>null</literal></term>
	  <listitem>
	  <para>
	  The second argument is a string that should be printed
	  whenever a column is null. The default is not to print
	  anything, which can easily be mistaken for, say, an empty
	  string. Thus, one might choose to write <literal>\pset null
	  '(null)'</literal>.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>fieldsep</literal></term>
	  <listitem>
	  <para>
	  Specifies the field separator to be used in unaligned output
	  mode. That way one can create, for example, tab- or
	  comma-separated output, which other programs might prefer. To
	  set a tab as field separator, type <literal>\pset fieldsep
	  '\t'</literal>. The default field separator is
	  <literal>'|'</literal> (a vertical bar).
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>footer</literal></term>
	  <listitem>
	  <para>
	  Toggles the display of the default footer <literal>(x
	  rows)</literal>.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>recordsep</literal></term>
	  <listitem>
	  <para>
          Specifies the record (line) separator to use in unaligned
          output mode. The default is a newline character.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
	  <listitem>
	  <para>
	  Toggles between tuples only and full display. Full display may
	  show extra information such as column headers, titles, and
	  various footers. In tuples only mode, only actual table data
	  is shown.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
	  <listitem>
	  <para>
	  Sets the table title for any subsequently printed tables. This
	  can be used to give your output descriptive tags. If no
	  argument is given, the title is unset.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
	  <listitem>
	  <para>
	  Allows you to specify any attributes to be placed inside the
	  <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
	  could for example be <literal>cellpadding</literal> or
	  <literal>bgcolor</literal>. Note that you probably don't want
	  to specify <literal>border</literal> here, as that is already
	  taken care of by <literal>\pset border</literal>.
	  </para>
	  </listitem>
	  </varlistentry>


	  <varlistentry>
	  <term><literal>pager</literal></term>
	  <listitem>
	  <para>
	  Controls use of a pager for query and <application>psql</>
	  help output. If the environment variable <envar>PAGER</envar>
	  is set, the output is piped to the specified program.
	  Otherwise a platform-dependent default (such as
	  <filename>more</filename>) is used.
	  </para>

	  <para>
	  When the pager is off, the pager is not used. When the pager
	  is on, the pager is used only when appropriate, i.e. the
	  output is to a terminal and will not fit on the screen.
	  (<application>psql</> does not do a perfect job of estimating
	  when to use the pager.) <literal>\pset pager</> turns the
	  pager on and off. Pager can also be set to <literal>always</>,
	  which causes the pager to be always used.
	  </para>
	  </listitem>
	  </varlistentry>
	</variablelist>
        </para>

        <para>
	Illustrations on how these different formats look can be seen in
	the <xref linkend="APP-PSQL-examples"
	endterm="APP-PSQL-examples-title"> section.
	</para>

	<tip>
	<para>
	There are various shortcut commands for <command>\pset</command>. See
	<command>\a</command>, <command>\C</command>, <command>\H</command>,
	<command>\t</command>, <command>\T</command>, and <command>\x</command>.
	</para>
	</tip>

	<note>
	<para>
	It is an error to call <command>\pset</command> without