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.

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 9d7f7346d95d925915adee65a6f836287bd600f9..82d3658a50b21aa3f1e736e543284a41473a6ac0 100644 (file)
--- 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 @@       lomowner       oid       pg_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 8045f5c95beed1d16231117447ca5d9df85a89de..d13e6d151f5226a987777a20417c3c628043758a 100644 (file)

--- 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 1cec73e4c025723b193f2193e2a945605e105c4d..90319c47feef9d445683cb4a48b381d61aa1a806 100644 (file)

--- 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 86879acedbcb1077f65d9a3b364c51da555f1849..8f920f57c7ab3c153eebebc44b9d4bbd03833338 100644 (file)

--- 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.
       
      
     

This is the main PostgreSQL git repository.
RSS
Atom

























window.onload = function () {
	var tz_cookie = { name: 'gitweb_tz', expires: 14, path: '/' };
	onloadTZSetup('local', tz_cookie, 'datetime');
};

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 8045f5c95beed1d16231117447ca5d9df85a89de..d13e6d151f5226a987777a20417c3c628043758a 100644 (file)
--- 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 1cec73e4c025723b193f2193e2a945605e105c4d..90319c47feef9d445683cb4a48b381d61aa1a806 100644 (file)
--- 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 86879acedbcb1077f65d9a3b364c51da555f1849..8f920f57c7ab3c153eebebc44b9d4bbd03833338 100644 (file)
--- 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.