mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation for pg_largeobject changes.

Browse Source 
Rewrite the documentation in more idiomatic English, and in the process make
it somewhat more succinct.  Move the discussion of specific large object
privileges out of the "server-side functions" section, where it certainly
doesn't belong, and into "implementation features".  That might not be
exactly right either, but it doesn't seem worth creating a new section for
this amount of information. Fix a few spelling and layout problems, too.
This commit is contained in:
Robert Haas 2009-12-17 14:36:16 +00:00
parent 36d192ad7d
commit f5fd651e1b
4 changed files with 48 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/src/sgml/catalogs.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.213 2009/12/11 03:34:54 itagaki Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.214 2009/12/17 14:36:15 rhaas Exp $ -->
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
-->
@ -3125,9 +3125,8 @@
<para>
The catalog <structname>pg_largeobject</structname> holds the data making up
<quote>large objects</quote>. A large object is identified by an OID of
<link linkend="catalog-pg-largeobject-metadata"><structname>pg_largeobject_metadata</></link>
catalog, assigned when it is created. Each large object is broken into
<quote>large objects</quote>. A large object is identified by an OID
assigned when it is created. Each large object is broken into
segments or <quote>pages</> small enough to be conveniently stored as rows
in <structname>pg_largeobject</structname>.
The amount of data per page is defined to be <symbol>LOBLKSIZE</> (which is currently
@ -3135,10 +3134,13 @@
</para>
<para>
<structname>pg_largeobject</structname> should not be readable by the
public, since the catalog contains data in large objects of all users.
<structname>pg_largeobject_metadata</> is a publicly readable catalog
that only contains identifiers of large objects.
Prior to <productname>PostgreSQL</> 8.5, there was no permission structure
associated with large objects. As a result,
<structname>pg_largeobject</structname> was publicly readable and could be
used to obtain the OIDs (and contents) of all large objects in the system.
This is no longer the case; use
<link linkend="catalog-pg-largeobject-metadata">pg_largeobject_metadata</link>
to obtain a list of large object OIDs.
</para>
<table>
@ -3202,9 +3204,10 @@
</indexterm>
<para>
The purpose of <structname>pg_largeobject_metadata</structname> is to
hold metadata of <quote>large objects</quote>, such as OID of its owner,
access permissions and OID of the large object itself.
The catalog <structname>pg_largeobject_metadata</structname>
holds metadata associated with large objects. The actual large object
data is stored in
<link linkend="catalog-pg-largeobject">pg_largeobject</link>.
</para>
<table>
@ -3225,12 +3228,13 @@
<entry><structfield>lomowner</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
<entry>Owner of the largeobejct</entry>
<entry>Owner of the largeobject</entry>
</row>
<row>
<entry><structfield>lomacl</structfield></entry>
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant" endterm="sql-grant-title"> and

25
doc/src/sgml/config.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.237 2009/12/11 03:34:55 itagaki Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.238 2009/12/17 14:36:16 rhaas Exp $ -->
<chapter Id="runtime-config">
<title>Server Configuration</title>
@ -4825,22 +4825,19 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
</indexterm>
<listitem>
<para>
This allows us to tuen on/off database privilege checks on large
objects. In the 8.4.x series and earlier release do not have
privilege checks on large object in most cases.
So, turning the <varname>lo_compat_privileges</varname> off means
the large object feature performs in compatible mode.
In <productname>PostgreSQL</> releases prior to 8.5, large objects
did not have access privileges and were, in effect, readable and
writable by all users. Setting this variable to <literal>on</>
disables the new privilege checks, for compatibility with prior
releases. The default is <literal>off</>.
</para>
<para>
Please note that it is not equivalent to disable all the security
checks corresponding to large objects.
For example, the <literal>lo_import()</literal> and
Setting this variable does not disable all security checks for
large objects - only those for which the default behavior has changed
in <productname>PostgreSQL</> 8.5.
For example, <literal>lo_import()</literal> and
<literal>lo_export()</literal> need superuser privileges independent
from this setting as prior versions were doing.
</para>
<para>
It is <literal>off</literal> by default.
of this setting.
</para>
</listitem>
</varlistentry>

70
doc/src/sgml/lobj.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.50 2009/12/11 03:34:55 itagaki Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.51 2009/12/17 14:36:16 rhaas Exp $ -->
<chapter id="largeObjects">
<title id="largeObjects-title">Large Objects</title>
@ -59,6 +59,21 @@
searches for the correct chunk number when doing random
access reads and writes.
</para>
<para>
As of <productname>PostgreSQL</> 8.5, large objects have an owner
and a set of access permissions, which can be managed using
<xref linkend="sql-grant" endterm="sql-grant-title"> and
<xref linkend="sql-revoke" endterm="sql-revoke-title">.
For compatibility with prior releases, see
<xref linkend="guc-lo-compat-privileges">.
<literal>SELECT</literal> privileges are required to read a large
object, and
<literal>UPDATE</literal> privileges are required to write to or
truncate it.
Only the large object owner (or the database superuser) can unlink, comment
on, or change the owner of a large object.
</para>
</sect1>
<sect1 id="lo-interfaces">
@ -438,60 +453,9 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
owning user. Therefore, their use is restricted to superusers. In
contrast, the client-side import and export functions read and write files
in the client's file system, using the permissions of the client program.
The client-side functions can be used by any
<productname>PostgreSQL</productname> user.
The client-side functions do not require superuser privilege.
</para>
<sect2 id="lo-func-privilege">
<title>Large object and privileges</title>
<para>
Note that access control feature was not supported in the 8.4.x series
and earlier release.
Also see the <xref linkend="guc-lo-compat-privileges"> compatibility
option.
</para>
<para>
Now it supports access controls on large objects, and allows the owner
of large objects to set up access rights using
<xref linkend="sql-grant" endterm="sql-grant-title"> and
<xref linkend="sql-revoke" endterm="sql-revoke-title"> statement.
</para>
<para>
Two permissions are defined on the large object class.
These are checked only when <xref linkend="guc-lo-compat-privileges">
option is disabled.
</para>
<para>
The first is <literal>SELECT</literal>.
It is required on <function>loread()</function> function.
Note that when we open large object with read-only mode, we can see
a static image even if other concurrent transaction modified the
same large object.
This principle is also applied on the access rights of large objects.
Even if a transaction modified access rights and commit it, it is
not invisible from other transaction which already opened the large
object.
</para>
<para>
The second is <literal>UPDATE</literal>.
It is required on <function>lowrite()</function> function and
<function>lo_truncate()</function> function.
</para>
<para>
In addition, <function>lo_unlink()</function> function,
<command>COMMENT ON</command> and <command>ALTER LARGE OBJECT</command>
statements needs ownership of the large object to be accessed.
</para>
<para>
You may wonder why <literal>SELECT</literal> is not checked on the
<function>lo_export()</function> function or <literal>UPDATE</literal>
is not checked on the <function>lo_import</function> function.
These functions originally require database superuser privilege,
and it allows to bypass the default database privilege checks,
so we don't need to check an obvious test twice.
</para>
</sect2>
</sect1>
<sect1 id="lo-examplesect">

9
doc/src/sgml/ref/grant.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.80 2009/12/11 03:34:55 itagaki Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.81 2009/12/17 14:36:16 rhaas Exp $
PostgreSQL documentation
-->
@ -174,8 +174,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
<xref linkend="sql-delete" endterm="sql-delete-title">.
For sequences, this privilege also allows the use of the
<function>currval</function> function.
For large objects, this privilege also allows to read from
the target large object.
For large objects, this privilege allows the object to be read.
</para>
</listitem>
</varlistentry>
@ -209,8 +208,8 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
<literal>SELECT</literal> privilege. For sequences, this
privilege allows the use of the <function>nextval</function> and
<function>setval</function> functions.
For large objects, this privilege also allows to write or truncate
on the target large object.
For large objects, this privilege allows writing or truncating the
object.
</para>
</listitem>
</varlistentry>