mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-12-27 08:39:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

Doc: write some for adminpack.

Browse Source 
Previous contents of adminpack.sgml were rather far short of project norms.
Not to mention being outright wrong about the signature of pg_file_read().
This commit is contained in:
Tom Lane 2016-08-10 21:39:50 -04:00
parent ab0a23c7c9
commit ff2fd6b06a
1 changed files with 140 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
doc/src/sgml/adminpack.sgml
View File

@ -12,29 +12,151 @@
<application>pgAdmin</> and other administration and management tools can
use to provide additional functionality, such as remote management
of server log files.
Use of all these functions is restricted to superusers.
</para>
<sect2>
<title>Functions Implemented</title>
<para>
The functions shown in <xref linkend="functions-adminpack-table"> provide
write access to files on the machine hosting the server. (See also the
functions in <xref linkend="functions-admin-genfile-table">, which
provide read-only access.)
Only files within the database cluster directory can be accessed, but
either a relative or absolute path is allowable.
</para>
<para>
The functions implemented by <filename>adminpack</> can only be run by a
superuser. Here's a list of these functions:
<table id="functions-adminpack-table">
<title><filename>adminpack</> Functions</title>
<tgroup cols="3">
<thead>
<row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
</row>
</thead>
<programlisting>
int8 pg_catalog.pg_file_write(fname text, data text, append bool)
bool pg_catalog.pg_file_rename(oldname text, newname text, archivename text)
bool pg_catalog.pg_file_rename(oldname text, newname text)
bool pg_catalog.pg_file_unlink(fname text)
setof record pg_catalog.pg_logdir_ls()
<tbody>
<row>
<entry><function>pg_catalog.pg_file_write(filename text, data text, append boolean)</function></entry>
<entry><type>bigint</type></entry>
<entry>
Write, or append to, a text file
</entry>
</row>
<row>
<entry><function>pg_catalog.pg_file_rename(oldname text, newname text <optional>, archivename text</optional>)</function></entry>
<entry><type>boolean</type></entry>
<entry>
Rename a file
</entry>
</row>
<row>
<entry><function>pg_catalog.pg_file_unlink(filename text)</function></entry>
<entry><type>boolean</type></entry>
<entry>
Remove a file
</entry>
</row>
<row>
<entry><function>pg_catalog.pg_logdir_ls()</function></entry>
<entry><type>setof record</type></entry>
<entry>
List the log files in the <varname>log_directory</> directory
</entry>
</row>
</tbody>
</tgroup>
</table>
/* Renaming of existing backend functions for pgAdmin compatibility */
int8 pg_catalog.pg_file_read(fname text, data text, append bool)
bigint pg_catalog.pg_file_length(text)
int4 pg_catalog.pg_logfile_rotate()
</programlisting>
</para>
<indexterm>
<primary>pg_file_write</primary>
</indexterm>
<para>
<function>pg_file_write</> writes the specified <parameter>data</> into
the file named by <parameter>filename</>. If <parameter>append</> is
false, the file must not already exist. If <parameter>append</> is true,
the file can already exist, and will be appended to if so.
Returns the number of bytes written.
</para>
</sect2>
<indexterm>
<primary>pg_file_rename</primary>
</indexterm>
<para>
<function>pg_file_rename</> renames a file. If <parameter>archivename</>
is omitted or NULL, it simply renames <parameter>oldname</>
to <parameter>newname</> (which must not already exist).
If <parameter>archivename</> is provided, it first
renames <parameter>newname</> to <parameter>archivename</> (which must
not already exist), and then renames <parameter>oldname</>
to <parameter>newname</>. In event of failure of the second rename step,
it will try to rename <parameter>archivename</> back
to <parameter>newname</> before reporting the error.
Returns true on success, false if the source file(s) are not present or
not writable; other cases throw errors.
</para>
<indexterm>
<primary>pg_file_unlink</primary>
</indexterm>
<para>
<function>pg_file_unlink</> removes the specified file.
Returns true on success, false if the specified file is not present
or the <function>unlink()</> call fails; other cases throw errors.
</para>
<indexterm>
<primary>pg_logdir_ls</primary>
</indexterm>
<para>
<function>pg_logdir_ls</> returns the start timestamps and path
names of all the log files in the <xref linkend="guc-log-directory">
directory. The <xref linkend="guc-log-filename"> parameter must have its
default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</>) to use this
function.
</para>
<para>
The functions shown
in <xref linkend="functions-adminpack-deprecated-table"> are deprecated
and should not be used in new applications; instead use those shown
in <xref linkend="functions-admin-signal-table">
and <xref linkend="functions-admin-genfile-table">. These functions are
provided in <filename>adminpack</> only for compatibility with old
versions of <application>pgAdmin</>.
</para>
<table id="functions-adminpack-deprecated-table">
<title>Deprecated <filename>adminpack</> Functions</title>
<tgroup cols="3">
<thead>
<row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><function>pg_catalog.pg_file_read(filename text, offset bigint, nbytes bigint)</function></entry>
<entry><type>text</type></entry>
<entry>
Alternate name for <function>pg_read_file()</>
</entry>
</row>
<row>
<entry><function>pg_catalog.pg_file_length(filename text)</function></entry>
<entry><type>bigint</type></entry>
<entry>
Same as <structfield>size</> column returned
by <function>pg_stat_file()</>
</entry>
</row>
<row>
<entry><function>pg_catalog.pg_logfile_rotate()</function></entry>
<entry><type>integer</type></entry>
<entry>
Alternate name for <function>pg_rotate_logfile()</>, but note that it
returns integer 0 or 1 rather than boolean
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>