rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation for pg_largeobject changes. 

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>