From f5fd651e1b96db6fa89ae540214e180ecf36a547 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Thu, 17 Dec 2009 14:36:16 +0000 Subject: [PATCH] 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. --- doc/src/sgml/catalogs.sgml | 28 ++++++++------- doc/src/sgml/config.sgml | 25 ++++++------- doc/src/sgml/lobj.sgml | 70 +++++++++---------------------------- doc/src/sgml/ref/grant.sgml | 9 +++-- 4 files changed, 48 insertions(+), 84 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 9d7f7346d9..82d3658a50 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,4 +1,4 @@ - + @@ -3125,9 +3125,8 @@ The catalog pg_largeobject holds the data making up - large objects. A large object is identified by an OID of - pg_largeobject_metadata - catalog, assigned when it is created. Each large object is broken into + large objects. A large object is identified by an OID + assigned when it is created. Each large object is broken into segments or pages small enough to be conveniently stored as rows in pg_largeobject. The amount of data per page is defined to be LOBLKSIZE (which is currently @@ -3135,10 +3134,13 @@ - pg_largeobject should not be readable by the - public, since the catalog contains data in large objects of all users. - pg_largeobject_metadata is a publicly readable catalog - that only contains identifiers of large objects. + Prior to PostgreSQL 8.5, there was no permission structure + associated with large objects. As a result, + pg_largeobject 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 + pg_largeobject_metadata + to obtain a list of large object OIDs. @@ -3202,9 +3204,10 @@ - The purpose of pg_largeobject_metadata is to - hold metadata of large objects, such as OID of its owner, - access permissions and OID of the large object itself. + The catalog pg_largeobject_metadata + holds metadata associated with large objects. The actual large object + data is stored in + pg_largeobject.
@@ -3225,12 +3228,13 @@ lomowneroidpg_authid.oid - Owner of the largeobejct + Owner of the largeobject lomacl aclitem[] + Access privileges; see and diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 8045f5c95b..d13e6d151f 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1,4 +1,4 @@ - + Server Configuration @@ -4825,22 +4825,19 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - 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 lo_compat_privileges off means - the large object feature performs in compatible mode. + In 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 on + disables the new privilege checks, for compatibility with prior + releases. The default is off. - Please note that it is not equivalent to disable all the security - checks corresponding to large objects. - For example, the lo_import() and + Setting this variable does not disable all security checks for + large objects - only those for which the default behavior has changed + in PostgreSQL 8.5. + For example, lo_import() and lo_export() need superuser privileges independent - from this setting as prior versions were doing. - - - It is off by default. + of this setting. diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 1cec73e4c0..90319c47fe 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,4 +1,4 @@ - + Large Objects @@ -59,6 +59,21 @@ searches for the correct chunk number when doing random access reads and writes. + + + As of PostgreSQL 8.5, large objects have an owner + and a set of access permissions, which can be managed using + and + . + For compatibility with prior releases, see + . + SELECT privileges are required to read a large + object, and + UPDATE 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. + @@ -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 - PostgreSQL user. + The client-side functions do not require superuser privilege. - - Large object and privileges - - Note that access control feature was not supported in the 8.4.x series - and earlier release. - Also see the compatibility - option. - - - Now it supports access controls on large objects, and allows the owner - of large objects to set up access rights using - and - statement. - - - Two permissions are defined on the large object class. - These are checked only when - option is disabled. - - - The first is SELECT. - It is required on loread() 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. - - - The second is UPDATE. - It is required on lowrite() function and - lo_truncate() function. - - - In addition, lo_unlink() function, - COMMENT ON and ALTER LARGE OBJECT - statements needs ownership of the large object to be accessed. - - - You may wonder why SELECT is not checked on the - lo_export() function or UPDATE - is not checked on the lo_import 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. - - diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 86879acedb..8f920f57c7 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,5 +1,5 @@ @@ -174,8 +174,7 @@ GRANT role_name [, ...] TO . For sequences, this privilege also allows the use of the currval 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. @@ -209,8 +208,8 @@ GRANT role_name [, ...] TO SELECT privilege. For sequences, this privilege allows the use of the nextval and setval 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.