345 lines
12 KiB
HTML
Executable File
345 lines
12 KiB
HTML
Executable File
<!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 1.1.7</h1>
|
|
<div class="navigation">
|
|
<a href="index.html">Top</a> >
|
|
<a href="pg_reorg.html">pg_reorg</a>
|
|
<div>
|
|
<hr />
|
|
|
|
<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="#releases">Releases</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 [OPTIONS]
|
|
</p>
|
|
|
|
<p>The following options can be specified in OPTIONS.
|
|
See also "<a href="#options">Options</a>" for details.</p>
|
|
<ul>
|
|
<li>Reorg Options<ul>
|
|
<li>-o [--order-by] columns [,...]</li>
|
|
<li>-n [--no-order]</li>
|
|
<li>-t [--table] table</li>
|
|
<li>-T [--wait-timeout] seconds</li>
|
|
<li>-Z [--no-analyze]</li>
|
|
</ul></li>
|
|
<li>Connection Options<ul>
|
|
<li>-a, --all : reorganize all databases</li>
|
|
<li>-d, --dbname=DBNAME : database to connect</li>
|
|
<li>-h, --host=HOSTNAME : database server host or socket directory</li>
|
|
<li>-p, --port=PORT : database server port</li>
|
|
<li>-U, --username=USERNAME : user name to connect as</li>
|
|
<li>-w, --no-password : never prompt for password</li>
|
|
<li>-W, --password : force password prompt</li>
|
|
</ul></li>
|
|
<li>Generic Options<ul>
|
|
<li>-e, --echo : echo queries</li>
|
|
<li>-E, --elevel=LEVEL : set output message level</li>
|
|
<li>--help : show the help, then exit</li>
|
|
<li>--version : output version information, then exit</li>
|
|
</ul></li>
|
|
</ul>
|
|
|
|
<h2 id="description">Description</h2>
|
|
<p>pg_reorg is an utility program to reorganize tables in PostgreSQL databases.
|
|
Unlike <a href="http://developer.postgresql.org/pgdocs/postgres/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 the following command line options:</p>
|
|
<dl>
|
|
|
|
<h3>Reorg Options</h3>
|
|
<p>Options to order rows.
|
|
If not specified, pg_reorg do online CLUSTER using cluster indexes.
|
|
Only one option can be specified.
|
|
|
|
Options to specify target tables or databases.
|
|
</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>
|
|
|
|
<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>
|
|
|
|
<dt>
|
|
-T seconds<br />
|
|
--wait-timeout=seconds
|
|
</dt>
|
|
<dd>
|
|
pg_reorg needs to take an exclusive lock at the end of the reorganization.
|
|
This setting controls how long it wait for acquiring the lock in seconds.
|
|
If the lock cannot be taken even after the duration, pg_reorg forces to cancel conflicted queries.
|
|
Also, if the server version is 8.4 or newer, pg_reorg forces to disconnect conflicted backends after twice time passed.
|
|
The default is 60 seconds.
|
|
</dd>
|
|
|
|
<dt>-Z<br />--no-analyze</dt>
|
|
<dd>Disable ANALYZE after the reorganization.
|
|
If not specified, run ANALYZE after the reorganization.</dd>
|
|
|
|
</dl>
|
|
|
|
<h3>Connection Options</h3>
|
|
<p>
|
|
Options to connect to servers.
|
|
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>-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 />
|
|
--no-password</dt>
|
|
<dd>
|
|
Never issue a password prompt.
|
|
If the server requires password authentication and a password is not available by other means such as a .pgpass 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.
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt>-W<br />
|
|
--password</dt>
|
|
<dd>Force the program to prompt for a password before connecting to a database.</dd>
|
|
<dd>This option is never essential, since the program 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>Generic Options</h3>
|
|
<dl>
|
|
<dt>-e<br />--echo</dt>
|
|
<dd>Echo commands sent to server.</dd>
|
|
<dt>-E<br />--elevel</dt>
|
|
<dd>Choose the output message level from DEBUG, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, and PANIC.
|
|
The default is INFO.</dd>
|
|
<dt>--help</dt>
|
|
<dd>Show usage of the program.</dd>
|
|
<dt>--version</dt>
|
|
<dd>Show the version number of the program.</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 built with "make" on UNIX or Linux.
|
|
pgxs build framework is used automatically.
|
|
Before build, you might need to install postgres packages for developper (postgresql-devel, etc.)
|
|
and add <code>pg_config</code> to your $PATH.
|
|
</p>
|
|
<pre>$ cd pg_reorg
|
|
$ make
|
|
$ su
|
|
$ make install</pre>
|
|
<p>
|
|
You can also use Microsoft Visual C++ 2010 to build the program on Windows.
|
|
There are project files in the msvc folder.
|
|
</p>
|
|
|
|
<p>Start PostgreSQL and execute the script to register functions to your database.</p>
|
|
<pre>$ pg_ctl start
|
|
$ psql -f $PGSHARE/contrib/pg_reorg.sql -d your_database</pre>
|
|
|
|
<p>(NOTE: <code>CREATE EXTENSION</code> is not supported yet.)</p>
|
|
|
|
<h2 id="requirement">Requirements</h2>
|
|
<dl>
|
|
<dt>PostgreSQL version</dt>
|
|
<dd>PostgreSQL 8.2, 8.3, 8.4, 9.0, 9.1</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. (If the total size of targets are 1GB, additional 2GB of disks are required.)</dd>
|
|
</dl>
|
|
|
|
<h2 id="releases">Releases</h2>
|
|
<ul>
|
|
<li>1.1.7 (2011-08-07)<ul>
|
|
<li>Bugfix: VIEWs and FUNCTIONs could be corrupted that used a reorganized table which has a dropped column.</li>
|
|
<li>Supports PostgreSQL 9.1 and 9.2dev. (but EXTENSION is not yet)</li>
|
|
</ul></li>
|
|
</ul>
|
|
|
|
<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 />
|
|
<div class="navigation">
|
|
<a href="index.html">Top</a> >
|
|
<a href="pg_reorg.html">pg_reorg</a>
|
|
<div>
|
|
<p class="footer">
|
|
Portions Copyright (c) 2008-2011, NIPPON TELEGRAPH AND TELEPHONE CORPORATION<br />
|
|
Portions Copyright (c) 2011, Itagaki Takahiro
|
|
</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>
|