farrokhi/pg_repack
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
pg_repack/doc/pg_reorg.html

279 lines
9.9 KiB
HTML
Raw Normal View History

Support reorganizing tables with non-default operator class.
2009-12-28 08:25:00 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>pg_reorg</title>
<link rel="home" title="pg_reorg " href="index.html">
<link rel="stylesheet" TYPE="text/css"href="style.css">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h1 id="pg_reorg">pg_reorg</h1>
<div class="index">
<ol>
<li><a href="#name">Name</a></li>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#description">Description</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#environment">Environment</a></li>
<li><a href="#restrictions">Restrictions</a></li>
<li><a href="#details">Details</a></li>
<li><a href="#install">Installations</a></li>
<li><a href="#requirement">Requirements</a></li>
<li><a href="#seealso">See Also</a></li>
</ol>
</div>
<h2 id="name">Name</h2>
pg_reorg -- Reorganize tables in PostgreSQL databases without any locks.
<h2 id="synopsis">Synopsis</h2>
<p>
pg_reorg [connection-options...] [message-options...] [order-options...] [target-options...]
</p>
<p>There 4 option categories.
See also <a href="#options">options</a> for details.</p>
<dl>
<dt>connection-options</dt>
<dd>-h [--host] host</dd>
<dd>-p [--port] port</dd>
<dd>-U [--username] username</dd>
<dd>-W [--password]</dd>
<dt>message-options</dt>
<dd>-q [--quiet]</dd>
<dd>-v [--verbose]</dd>
<dt>order-options</dt>
<dd>-o [--order-by] columns [,...]</dd>
<dd>-n [--no-order]</dd>
<dt>target-options</dt>
<dd>-a [--all]</dd>
<dd>-d [--dbname] dbname</dd>
<dd>-t [--table] table</dd>
<dd>-Z [--no-analyze]</dd>
</dl>
<h2 id="description">Description</h2>
<p>pg_reorg is an utility program to reorganize tables in PostgreSQL databases.
Unlike <a href="http://www.postgresql.jp/document/current/html/app-clusterdb.html">clusterdb</a>, it doesn't block any selections and updates during reorganization.
You can choose one of the following methods to reorganize.</p>
<ul>
<li>Online CLUSTER (ordered by cluster index)</li>
<li>Ordered by specified columns</li>
<li>Online VACUUM FULL (packing rows only)</li>
</ul>
<p>NOTICE:</p>
<ul>
<li>Only superusers can use the utility.</li>
<li>Target table must have PRIMARY KEY.</li>
</ul>
<h2 id="examples">Examples</h2>
<p>Execute the following command to do online CLUSTER to all tables in test database.</p>
<PRE><SAMP>$ </SAMP><KBD>pg_reorg test</KBD></PRE>
<p>Execute the following command to do online VACUUM FULL to foo table in test database.</p>
<PRE><SAMP>$ </SAMP><KBD>pg_reorg --no-order --table foo -d test</KBD></PRE><p>
</p>
<h2 id="options">Options</h2>
<p>pg_reorg has command line options in 4 categolies.</p>
<div>
<dl>
<h3>connection-options</h3>
<p>Parameters to connect PostgreSQL.</p>
<div>
<dl>
<dt>-h host<br />
--host host</dt>
<dd>Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. </dd>
<dt>-p port<br />
--port port</dt>
<dd>Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections.</dd>
<dt>-U username<br />
--username username</dt>
<dd>User name to connect as. </dd>
<dt>-W<br />--password</dt>
<dd>Force pg_reorg to prompt for a password before connecting to a database.</dd>
<dd>This option is never essential, since pg_reorg will automatically prompt for a password if the server demands password authentication. However, vacuumdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. </dd>
</dl>
<h3>message-options</h3>
<p>Specifies message output by pg_reorg.
--quiet is ignored if some of the other options are specified.</p>
<dl>
<dt>-q<br />--quiet</dt>
<dd>Do not display progress messages. </dd>
<dt>-v<br />--verbose</dt>
<dd>Print detailed information during processing.</dd>
</dl>
<h3>order-options</h3>
<p>Options to order rows.
If not specified, pg_reorg do online CLUSTER using cluster indexes.
Only one option can be specified.
</p>
<dl>
<dt>-n<br />--no-order</dt>
<dd>Do online VACUUM FULL.</dd>
<dt>-o columns [,...]<br />
--order-by columns [,...]</dt>
<dd>Do online CLUSTER ordered by specified columns.</dd>
</dl>
<h3>target-options</h3>
<p>
Options to specify target tables or databases.
You cannot use --all and --dbname or --table together.
</p>
<dl>
<dt>-a<br />--all</dt>
<dd>Reorganize all databases.</dd>
<dt>
-d dbname<br />
--dbname dbname
</dt>
<dd>Specifies the name of the database to be reorganized. If this is not specified and -a (or --all) is not used, the database name is read from the environment variable PGDATABASE. If that is not set, the user name specified for the connection is used. </dd>
<dt>
-t table<br />
--table table
</dt>
<dd>Reorganize table only. If you don't specify this option, all tables in specified databases are reorganized.</dd>
<dt>-Z<br />--no-analyze</dt>
<dd>Do ANALYZE after reorganization. If you don't specify this option, ANALYZE is performed automatically after reorg.</dd>
</dl>
<h2 id="environment">Environment</h2>
<dl>
<dt>
PGDATABASE<br />
PGHOST<br />
PGPORT<br />
PGUSER
</dt>
<dd>Default connection parameters</dd>
</dl>
<p>This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see <a href="http://developer.postgresql.org/pgdocs/postgres/libpq-envars.html">Environment Variables</a>).</p>
<h2 id="diagnostics">Diagnostics</h2>
<p>Error messages are reported when pg_reorg fails.
The following list shows the cause of errors.</p>
<p>You need to cleanup by hand after fatal erros.
To cleanup, execute $PGHOME/share/contrib/uninstall_pg_reorg.sql to the database where the error occured and then execute $PGHOME/share/contrib/pg_reorg.sql. (Do uninstall and reinstall.)</p>
<dl>
<dt>pg_reorg : reorg database "template1" ... skipped</dt>
<dd>pg_reorg is not installed in the database when --all option is specified.</dd>
<dd>Do register pg_reorg to the database.</dd>
<dt>ERROR: pg_reorg is not installed</dt>
<dd>pg_reorg is not installed in the database specified by --dbname.</dd>
<dd>Do register pg_reorg to the database.</dd>
<dt>ERROR: relation "table" has no primary key</dt>
<dd>The target table doesn't have PRIMARY KEY.</dd>
<dd>Define PRIMARY KEY to the table. (ALTER TABLE ADD PRIMARY KEY)</dd>
<dt>ERROR: relation "table" has no cluster key</dt>
<dd>The target table doesn't have CLUSTER KEY.</dd>
<dd>Define CLUSTER KEY to the table. (ALTER TABLE CLUSTER)</dd>
<dt>pg_reorg : query failed: ERROR: column "col" does not exist</dt>
<dd>The target table doesn't have columns specified by --order-by option.</dd>
<dd>Specify existing columns.</dd>
<dt>ERROR: permission denied for schema reorg</dt>
<dd>Permission error.</dd>
<dd>pg_reorg must be executed by superusers.</dd>
<dt>pg_reorg : query failed: ERROR: trigger "z_reorg_trigger" for relation "tbl" already exists</dt>
<dd>The target table already has a trigger named "z_reorg_trigger".</dd>
<dd>Delete or rename the trigger.</dd>
<dt>pg_reorg : trigger conflicted for tbl</dt>
<dd>The target table already has a trigger which follows by "z_reorg_trigger" in alphabetical order.</dd>
<dd>Delete or rename the trigger.</dd>
</dl>
<h2 id="restrictions">Restrictions</h2>
<p>pg_reorg has the following restrictions.
Be careful to avoid data corruptions.</p>
<h3>Temp tables</h3>
<p>pg_reorg cannot reorganize temp tables.</p>
<h3>GiST indexes</h3>
<p>pg_reorg cannot reorganize tables using GiST indexes.</p>
<h3>DDL commands</h3>
<p>You cannot do DDL commands <strong>except</strong> VACUUM and ANALYZE during pg_reorg.
In many case pg_reorg would fail and rollback collectly, but there are some cases ending with data-corruption .</p>
<dl>
<dt>TRUNCATE</dt>
<dd>TRUNCATE is lost. Deleted rows still exist after pg_reorg.</dd>
<dt>CREATE INDEX</dt>
<dd>It causes index corruptions.</dd>
<dt>ALTER TABLE ... ADD COLUMN</dt>
<dd>It causes lost of data. Newly added columns are initialized with NULLs.</dd>
<dt>ALTER TABLE ... ALTER COLUMN TYPE</dt>
<dd>It causes data corruptions.</dd>
<dt>ALTER TABLE ... SET TABLESPACE</dt>
<dd>It causes data corruptions by wrong relfilenode.</dd>
</dl>
<h2 id="details">Details</h2>
<p>pg_reorg creates a work table in reorg schema and sorts rows in it.
Then, it updates system catalog directly to swap the work table and the original one.</p>
<h2 id="install">Installations</h2>
<p>pg_reorg can be installed like standard contrib modules.</p>
<h3>Build from source</h3>
<p>Place pg_reorg to $PGHOME/contrib/ and input make, make install.</p>
<h3>Register to database</h3>
<p>Start PostgreSQL and execute pg_reorg.sql in $PGHOME/share/contrib.</p>
<h2 id="requirement">Requirements</h2>
<dl>
<dt>PostgreSQL version</dt><dd>PostgreSQL 8.3</dd>
<dt>OS</dt><dd>RHEL 5.2, Windows XP SP3</dd>
<dt>Disks</dt><dd>Requires amount of disks twice larger than target table and indexes.</dd>
</dl>
<h2 id="seealso">See Also</h2>
<a href="http://developer.postgresql.org/pgdocs/postgres/app-clusterdb.html">clusterdb</a>,
<a href="http://developer.postgresql.org/pgdocs/postgres/app-vacuumdb.html">vacuumdb</a>
<hr />
<p class="footer">Copyright (c) 2008-2009, NIPPON TELEGRAPH AND TELEPHONE CORPORATION</p>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-10244036-4");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>
Reference in New Issue Copy Permalink