<!-- $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

-->

<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

<literal>BLCKSZ/4</>, or typically 2 kB).

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

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

<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 thelargeobejct</entry>

<entry>Owner of thelargeobject</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

<!-- $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>

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

<!-- $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>

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

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

<!--

$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

-->

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

<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 privilegealsoallowsto writeortruncate

on the target largeobject.

For large objects, this privilege allowswritingortruncating the

object.

</para>

</listitem>

</varlistentry>