doc/src/sgml/ref/drop_table.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-DROPTABLE">
   7  <refmeta>
   8   <refentrytitle id="SQL-DROPTABLE-TITLE">DROP TABLE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>DROP TABLE</refname>
  15   <refpurpose>remove a table</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-droptable">
  19   <primary>DROP TABLE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 DROP TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>DROP TABLE</command> removes tables from the database.
  33    Only its owner can drop a table.  To empty a table of rows
  34    without destroying the table, use <xref linkend="sql-delete"
  35    endterm="sql-delete-title"> or <xref linkend="sql-truncate"
  36    endterm="sql-truncate-title">.
  37   </para>
  38
  39   <para>
  40    <command>DROP TABLE</command> always removes any indexes, rules,
  41    triggers, and constraints that exist for the target table.
  42    However, to drop a table that is referenced by a view or a foreign-key
  43    constraint of another table, <literal>CASCADE</> must be
  44    specified. (<literal>CASCADE</> will remove a dependent view entirely,
  45    but in the foreign-key case it will only remove the foreign-key
  46    constraint, not the other table entirely.)
  47   </para>
  48  </refsect1>
  49
  50  <refsect1>
  51   <title>Parameters</title>
  52
  53   <variablelist>
  54    <varlistentry>
  55     <term><literal>IF EXISTS</literal></term>
  56     <listitem>
  57      <para>
  58       Do not throw an error if the table does not exist. A notice is issued
  59       in this case.
  60      </para>
  61     </listitem>
  62    </varlistentry>
  63
  64    <varlistentry>
  65     <term><replaceable class="PARAMETER">name</replaceable></term>
  66     <listitem>
  67      <para>
  68       The name (optionally schema-qualified) of the table to drop.
  69      </para>
  70     </listitem>
  71    </varlistentry>
  72
  73    <varlistentry>
  74     <term><literal>CASCADE</literal></term>
  75     <listitem>
  76      <para>
  77       Automatically drop objects that depend on the table (such as
  78       views).
  79      </para>
  80     </listitem>
  81    </varlistentry>
  82
  83    <varlistentry>
  84     <term><literal>RESTRICT</literal></term>
  85     <listitem>
  86      <para>
  87       Refuse to drop the table if any objects depend on it.  This is
  88       the default.
  89      </para>
  90     </listitem>
  91    </varlistentry>
  92   </variablelist>
  93  </refsect1>
  94
  95  <refsect1>
  96   <title>Examples</title>
  97
  98   <para>
  99    To destroy two tables, <literal>films</literal> and
 100    <literal>distributors</literal>:
 101
 102 <programlisting>
 103 DROP TABLE films, distributors;
 104 </programlisting>
 105   </para>
 106  </refsect1>
 107
 108  <refsect1>
 109   <title>Compatibility</title>
 110
 111   <para>
 112    This command conforms to the SQL standard, except that the standard only
 113    allows one table to be dropped per command, and apart from the
 114    <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</>
 115    extension.
 116   </para>
 117  </refsect1>
 118
 119  <refsect1>
 120   <title>See Also</title>
 121
 122   <simplelist type="inline">
 123    <member><xref linkend="sql-altertable" endterm="sql-altertable-title"></member>
 124    <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
 125   </simplelist>
 126  </refsect1>
 127
 128 </refentry>