open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues 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.
REL8_5_ALPHA3_BRANCH
Robert Haas 16 years ago
parent 36d192ad7d
commit f5fd651e1b
4 changed files with 48 additions and 84 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 28
      doc/src/sgml/catalogs.sgml
  2. 25
      doc/src/sgml/config.sgml
  3. 70
      doc/src/sgml/lobj.sgml
  4. 9
      doc/src/sgml/ref/grant.sgml

28
doc/src/sgml/catalogs.sgml
Unescape 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 Documentation of the system catalogs, directed toward PostgreSQL developers
--> -->
@ -3125,9 +3125,8 @@
<para> <para>
The catalog <structname>pg_largeobject</structname> holds the data making up The catalog <structname>pg_largeobject</structname> holds the data making up
<quote>large objects</quote>. A large object is identified by an OID of <quote>large objects</quote>. A large object is identified by an OID
<link linkend="catalog-pg-largeobject-metadata"><structname>pg_largeobject_metadata</></link> assigned when it is created. Each large object is broken into
catalog, assigned when it is created. Each large object is broken into
segments or <quote>pages</> small enough to be conveniently stored as rows segments or <quote>pages</> small enough to be conveniently stored as rows
in <structname>pg_largeobject</structname>. in <structname>pg_largeobject</structname>.
The amount of data per page is defined to be <symbol>LOBLKSIZE</> (which is currently The amount of data per page is defined to be <symbol>LOBLKSIZE</> (which is currently
@ -3135,10 +3134,13 @@
</para> </para>
<para> <para>
<structname>pg_largeobject</structname> should not be readable by the Prior to <productname>PostgreSQL</> 8.5, there was no permission structure
public, since the catalog contains data in large objects of all users. associated with large objects. As a result,
<structname>pg_largeobject_metadata</> is a publicly readable catalog <structname>pg_largeobject</structname> was publicly readable and could be
that only contains identifiers of large objects. 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> </para>
<table> <table>
@ -3202,9 +3204,10 @@
</indexterm> </indexterm>
<para> <para>
The purpose of <structname>pg_largeobject_metadata</structname> is to The catalog <structname>pg_largeobject_metadata</structname>
hold metadata of <quote>large objects</quote>, such as OID of its owner, holds metadata associated with large objects. The actual large object
access permissions and OID of the large object itself. data is stored in
<link linkend="catalog-pg-largeobject">pg_largeobject</link>.
</para> </para>
<table> <table>
@ -3225,12 +3228,13 @@
<entry><structfield>lomowner</structfield></entry> <entry><structfield>lomowner</structfield></entry>
<entry><type>oid</type></entry> <entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></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>
<row> <row>
<entry><structfield>lomacl</structfield></entry> <entry><structfield>lomacl</structfield></entry>
<entry><type>aclitem[]</type></entry> <entry><type>aclitem[]</type></entry>
<entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant" endterm="sql-grant-title"> and <xref linkend="sql-grant" endterm="sql-grant-title"> and

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

70
doc/src/sgml/lobj.sgml
Unescape 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"> <chapter id="largeObjects">
<title id="largeObjects-title">Large Objects</title> <title id="largeObjects-title">Large Objects</title>
@ -59,6 +59,21 @@
searches for the correct chunk number when doing random searches for the correct chunk number when doing random
access reads and writes. access reads and writes.
</para> </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>
<sect1 id="lo-interfaces"> <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 owning user. Therefore, their use is restricted to superusers. In
contrast, the client-side import and export functions read and write files 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. in the client's file system, using the permissions of the client program.
The client-side functions can be used by any The client-side functions do not require superuser privilege.
<productname>PostgreSQL</productname> user.
</para> </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>
<sect1 id="lo-examplesect"> <sect1 id="lo-examplesect">

9
doc/src/sgml/ref/grant.sgml
Unescape 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 PostgreSQL documentation
--> -->
@ -174,8 +174,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
<xref linkend="sql-delete" endterm="sql-delete-title">. <xref linkend="sql-delete" endterm="sql-delete-title">.
For sequences, this privilege also allows the use of the For sequences, this privilege also allows the use of the
<function>currval</function> function. <function>currval</function> function.
For large objects, this privilege also allows to read from For large objects, this privilege allows the object to be read.
the target large object.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -209,8 +208,8 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
<literal>SELECT</literal> privilege. For sequences, this <literal>SELECT</literal> privilege. For sequences, this
privilege allows the use of the <function>nextval</function> and privilege allows the use of the <function>nextval</function> and
<function>setval</function> functions. <function>setval</function> functions.
For large objects, this privilege also allows to write or truncate For large objects, this privilege allows writing or truncating the
on the target large object. object.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

Write Preview
Loading…
Cancel
Save