doc/src/sgml/ref/truncate.sgml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/truncate.sgml,v 1.21 2006/09/16 00:30:20 momjian Exp $
PostgreSQL documentation
-->

<refentry id="SQL-TRUNCATE">
 <refmeta>
  <refentrytitle id="SQL-TRUNCATE-TITLE">TRUNCATE</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>TRUNCATE</refname>
  <refpurpose>empty a table or set of tables</refpurpose>
 </refnamediv>

 <indexterm zone="sql-truncate">
  <primary>TRUNCATE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>TRUNCATE</command> quickly removes all rows from a set of
   tables. It has the same effect as an unqualified
   <command>DELETE</command> on each table, but since it does not actually
   scan the tables it is faster. This is most useful on large tables.
  </para>
 </refsect1>
  
 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="PARAMETER">name</replaceable></term>
    <listitem>
     <para>
      The name (optionally schema-qualified) of a table to be truncated.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>CASCADE</literal></term>
    <listitem>
     <para>
      Automatically truncate all tables that have foreign-key references
      to any of the named tables, or to any tables added to the group
      due to <literal>CASCADE</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>RESTRICT</literal></term>
    <listitem>
     <para>
      Refuse to truncate if any of the tables have foreign-key references
      from tables that are not to be truncated.  This is the default.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Only the owner of a table may <command>TRUNCATE</> it.
  </para>

  <para>
   <command>TRUNCATE</> cannot be used on a table that has foreign-key
   references from other tables, unless all such tables are also truncated
   in the same command.  Checking validity in such cases would require table
   scans, and the whole point is not to do one.  The <literal>CASCADE</>
   option can be used to automatically include all dependent tables &mdash;
   but be very careful when using this option, else you might lose data you
   did not intend to!
  </para>

  <para>
   <command>TRUNCATE</> will not run any user-defined <literal>ON
   DELETE</literal> triggers that might exist for the tables.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Truncate the tables <literal>bigtable</literal> and <literal>fattable</literal>:

<programlisting>
TRUNCATE TABLE bigtable, fattable;
</programlisting>
  </para>

  <para>
   Truncate the table <literal>othertable</literal>, and cascade to any tables
   that are referencing <literal>othertable</literal> via foreign-key
   constraints:

<programlisting>
TRUNCATE othertable CASCADE;
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   There is no <command>TRUNCATE</command> command in the SQL standard.
  </para>
 </refsect1>
</refentry>