Skip to content

Commit f5fd651

Browse files
robertmhaasrobertmhaas
committed
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.
1 parent 36d192a commit f5fd651

File tree

4 files changed

+48
-84
lines changed

4 files changed

+48
-84
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.213 2009/12/11 03:34:54 itagaki Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.214 2009/12/17 14:36:15 rhaas Exp $ -->
22
<!--
33
Documentation of the system catalogs, directed toward PostgreSQL developers
44
-->
@@ -3125,20 +3125,22 @@
31253125

31263126
<para>
31273127
The catalog <structname>pg_largeobject</structname> holds the data making up
3128-
<quote>large objects</quote>. A large object is identified by an OID of
3129-
<link linkend="catalog-pg-largeobject-metadata"><structname>pg_largeobject_metadata</></link>
3130-
catalog, assigned when it is created. Each large object is broken into
3128+
<quote>large objects</quote>. A large object is identified by an OID
3129+
assigned when it is created. Each large object is broken into
31313130
segments or <quote>pages</> small enough to be conveniently stored as rows
31323131
in <structname>pg_largeobject</structname>.
31333132
The amount of data per page is defined to be <symbol>LOBLKSIZE</> (which is currently
31343133
<literal>BLCKSZ/4</>, or typically 2 kB).
31353134
</para>
31363135

31373136
<para>
3138-
<structname>pg_largeobject</structname> should not be readable by the
3139-
public, since the catalog contains data in large objects of all users.
3140-
<structname>pg_largeobject_metadata</> is a publicly readable catalog
3141-
that only contains identifiers of large objects.
3137+
Prior to <productname>PostgreSQL</> 8.5, there was no permission structure
3138+
associated with large objects. As a result,
3139+
<structname>pg_largeobject</structname> was publicly readable and could be
3140+
used to obtain the OIDs (and contents) of all large objects in the system.
3141+
This is no longer the case; use
3142+
<link linkend="catalog-pg-largeobject-metadata">pg_largeobject_metadata</link>
3143+
to obtain a list of large object OIDs.
31423144
</para>
31433145

31443146
<table>
@@ -3202,9 +3204,10 @@
32023204
</indexterm>
32033205

32043206
<para>
3205-
The purpose of <structname>pg_largeobject_metadata</structname> is to
3206-
hold metadata of <quote>large objects</quote>, such as OID of its owner,
3207-
access permissions and OID of the large object itself.
3207+
The catalog <structname>pg_largeobject_metadata</structname>
3208+
holds metadata associated with large objects. The actual large object
3209+
data is stored in
3210+
<link linkend="catalog-pg-largeobject">pg_largeobject</link>.
32083211
</para>
32093212

32103213
<table>
@@ -3225,12 +3228,13 @@
32253228
<entry><structfield>lomowner</structfield></entry>
32263229
<entry><type>oid</type></entry>
32273230
<entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
3228-
<entry>Owner of the largeobejct</entry>
3231+
<entry>Owner of the largeobject</entry>
32293232
</row>
32303233

32313234
<row>
32323235
<entry><structfield>lomacl</structfield></entry>
32333236
<entry><type>aclitem[]</type></entry>
3237+
<entry></entry>
32343238
<entry>
32353239
Access privileges; see
32363240
<xref linkend="sql-grant" endterm="sql-grant-title"> and

‎doc/src/sgml/config.sgml

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.237 2009/12/11 03:34:55 itagaki Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.238 2009/12/17 14:36:16 rhaas Exp $ -->
22

33
<chapter Id="runtime-config">
44
<title>Server Configuration</title>
@@ -4825,22 +4825,19 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
48254825
</indexterm>
48264826
<listitem>
48274827
<para>
4828-
This allows us to tuen on/off database privilege checks on large
4829-
objects. In the 8.4.x series and earlier release do not have
4830-
privilege checks on large object in most cases.
4831-
4832-
So, turning the <varname>lo_compat_privileges</varname> off means
4833-
the large object feature performs in compatible mode.
4828+
In <productname>PostgreSQL</> releases prior to 8.5, large objects
4829+
did not have access privileges and were, in effect, readable and
4830+
writable by all users. Setting this variable to <literal>on</>
4831+
disables the new privilege checks, for compatibility with prior
4832+
releases. The default is <literal>off</>.
48344833
</para>
48354834
<para>
4836-
Please note that it is not equivalent to disable all the security
4837-
checks corresponding to large objects.
4838-
For example, the <literal>lo_import()</literal> and
4835+
Setting this variable does not disable all security checks for
4836+
large objects - only those for which the default behavior has changed
4837+
in <productname>PostgreSQL</> 8.5.
4838+
For example, <literal>lo_import()</literal> and
48394839
<literal>lo_export()</literal> need superuser privileges independent
4840-
from this setting as prior versions were doing.
4841-
</para>
4842-
<para>
4843-
It is <literal>off</literal> by default.
4840+
of this setting.
48444841
</para>
48454842
</listitem>
48464843
</varlistentry>

‎doc/src/sgml/lobj.sgml

Lines changed: 17 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.50 2009/12/11 03:34:55 itagaki Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.51 2009/12/17 14:36:16 rhaas Exp $ -->
22

33
<chapter id="largeObjects">
44
<title id="largeObjects-title">Large Objects</title>
@@ -59,6 +59,21 @@
5959
searches for the correct chunk number when doing random
6060
access reads and writes.
6161
</para>
62+
63+
<para>
64+
As of <productname>PostgreSQL</> 8.5, large objects have an owner
65+
and a set of access permissions, which can be managed using
66+
<xref linkend="sql-grant" endterm="sql-grant-title"> and
67+
<xref linkend="sql-revoke" endterm="sql-revoke-title">.
68+
For compatibility with prior releases, see
69+
<xref linkend="guc-lo-compat-privileges">.
70+
<literal>SELECT</literal> privileges are required to read a large
71+
object, and
72+
<literal>UPDATE</literal> privileges are required to write to or
73+
truncate it.
74+
Only the large object owner (or the database superuser) can unlink, comment
75+
on, or change the owner of a large object.
76+
</para>
6277
</sect1>
6378

6479
<sect1 id="lo-interfaces">
@@ -438,60 +453,9 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
438453
owning user. Therefore, their use is restricted to superusers. In
439454
contrast, the client-side import and export functions read and write files
440455
in the client's file system, using the permissions of the client program.
441-
The client-side functions can be used by any
442-
<productname>PostgreSQL</productname> user.
456+
The client-side functions do not require superuser privilege.
443457
</para>
444458

445-
<sect2 id="lo-func-privilege">
446-
<title>Large object and privileges</title>
447-
<para>
448-
Note that access control feature was not supported in the 8.4.x series
449-
and earlier release.
450-
Also see the <xref linkend="guc-lo-compat-privileges"> compatibility
451-
option.
452-
</para>
453-
<para>
454-
Now it supports access controls on large objects, and allows the owner
455-
of large objects to set up access rights using
456-
<xref linkend="sql-grant" endterm="sql-grant-title"> and
457-
<xref linkend="sql-revoke" endterm="sql-revoke-title"> statement.
458-
</para>
459-
<para>
460-
Two permissions are defined on the large object class.
461-
These are checked only when <xref linkend="guc-lo-compat-privileges">
462-
option is disabled.
463-
</para>
464-
<para>
465-
The first is <literal>SELECT</literal>.
466-
It is required on <function>loread()</function> function.
467-
Note that when we open large object with read-only mode, we can see
468-
a static image even if other concurrent transaction modified the
469-
same large object.
470-
This principle is also applied on the access rights of large objects.
471-
Even if a transaction modified access rights and commit it, it is
472-
not invisible from other transaction which already opened the large
473-
object.
474-
</para>
475-
<para>
476-
The second is <literal>UPDATE</literal>.
477-
It is required on <function>lowrite()</function> function and
478-
<function>lo_truncate()</function> function.
479-
</para>
480-
<para>
481-
In addition, <function>lo_unlink()</function> function,
482-
<command>COMMENT ON</command> and <command>ALTER LARGE OBJECT</command>
483-
statements needs ownership of the large object to be accessed.
484-
</para>
485-
<para>
486-
You may wonder why <literal>SELECT</literal> is not checked on the
487-
<function>lo_export()</function> function or <literal>UPDATE</literal>
488-
is not checked on the <function>lo_import</function> function.
489-
490-
These functions originally require database superuser privilege,
491-
and it allows to bypass the default database privilege checks,
492-
so we don't need to check an obvious test twice.
493-
</para>
494-
</sect2>
495459
</sect1>
496460

497461
<sect1 id="lo-examplesect">

‎doc/src/sgml/ref/grant.sgml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.80 2009/12/11 03:34:55 itagaki Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.81 2009/12/17 14:36:16 rhaas Exp $
33
PostgreSQL documentation
44
-->
55

@@ -174,8 +174,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
174174
<xref linkend="sql-delete" endterm="sql-delete-title">.
175175
For sequences, this privilege also allows the use of the
176176
<function>currval</function> function.
177-
For large objects, this privilege also allows to read from
178-
the target large object.
177+
For large objects, this privilege allows the object to be read.
179178
</para>
180179
</listitem>
181180
</varlistentry>
@@ -209,8 +208,8 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
209208
<literal>SELECT</literal> privilege. For sequences, this
210209
privilege allows the use of the <function>nextval</function> and
211210
<function>setval</function> functions.
212-
For large objects, this privilege also allows to write or truncate
213-
on the target large object.
211+
For large objects, this privilege allows writing or truncating the
212+
object.
214213
</para>
215214
</listitem>
216215
</varlistentry>

0 commit comments

Comments
 (0)