diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index ceedbc9c..dea10417 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -40,18 +40,20 @@ functionalities defined by the |DBAPI|_. The class can be subclassed: see the `connection.lobject()` to know how to specify a `!lobject` subclass. - + .. versionadded:: 2.0.8 .. attribute:: oid Database OID of the object. + .. attribute:: mode The mode the database was open. See `connection.lobject()` for a description of the available modes. + .. method:: read(bytes=-1) Read a chunk of data from the current file position. If -1 (default) @@ -64,6 +66,7 @@ functionalities defined by the |DBAPI|_. .. versionchanged:: 2.4 added Unicode support. + .. method:: write(str) Write a string to the large object. Return the number of bytes @@ -73,42 +76,60 @@ functionalities defined by the |DBAPI|_. .. versionchanged:: 2.4 added Unicode support. + .. method:: export(file_name) Export the large object content to the file system. - + The method uses the efficient |lo_export|_ libpq function. - + .. |lo_export| replace:: `!lo_export()` .. _lo_export: http://www.postgresql.org/docs/current/static/lo-interfaces.html#LO-EXPORT + .. method:: seek(offset, whence=0) Set the lobject current position. + .. versionchanged:: 2.6.0 + added support for *offset* > 2GB. + + .. method:: tell() Return the lobject current position. - .. method:: truncate(len=0) - .. versionadded:: 2.2.0 + .. versionchanged:: 2.6.0 + added support for return value > 2GB. + + + .. method:: truncate(len=0) + Truncate the lobject to the given size. - The method will only be available if Psycopg has been built against libpq - from PostgreSQL 8.3 or later and can only be used with PostgreSQL servers - running these versions. It uses the |lo_truncate|_ libpq function. + The method will only be available if Psycopg has been built against + libpq from PostgreSQL 8.3 or later and can only be used with + PostgreSQL servers running these versions. It uses the |lo_truncate|_ + libpq function. .. |lo_truncate| replace:: `!lo_truncate()` .. _lo_truncate: http://www.postgresql.org/docs/current/static/lo-interfaces.html#LO-TRUNCATE - .. warning:: + .. versionadded:: 2.2.0 + + .. versionchanged:: 2.6.0 + added support for *len* > 2GB. + + .. warning:: + + If Psycopg is built with |lo_truncate| support or with the 64 bits API + support (resp. from PostgreSQL versions 8.3 and 9.3) but at runtime an + older version of the dynamic library is found, the ``psycopg2`` module + will fail to import. See :ref:`the lo_truncate FAQ ` + about the problem. - If Psycopg is built with |lo_truncate| support (i.e. if the - :program:`pg_config` used during setup is version >= 8.3), but at - runtime an older libpq is found, Psycopg will fail to import. See - :ref:`the lo_truncate FAQ ` about the problem. .. method:: close() diff --git a/doc/src/faq.rst b/doc/src/faq.rst index 0646cdff..8f2f1ecc 100644 --- a/doc/src/faq.rst +++ b/doc/src/faq.rst @@ -248,13 +248,20 @@ I can't compile `!psycopg2`: the compiler says *error: libpq-fe.h: No such file .. cssclass:: faq `!psycopg2` raises `!ImportError` with message *_psycopg.so: undefined symbol: lo_truncate* when imported. - This means that Psycopg has been compiled with |lo_truncate|_ support, - which means that the libpq used at compile time was version >= 8.3, but at - runtime an older libpq library is found. You can use:: + This means that Psycopg was compiled with |lo_truncate|_ support (*i.e.* + the libpq used at compile time was version >= 8.3) but at runtime an older + libpq dynamic library is found. + + Fast-forward several years, if the message reports *undefined symbol: + lo_truncate64* it means that Psycopg was built with large objects 64 bits + API support (*i.e.* the libpq used at compile time was at least 9.3) but + at runtime an older libpq dynamic library is found. + + You can use:: $ ldd /path/to/packages/psycopg2/_psycopg.so | grep libpq - to find what is the version used at runtime. + to find what is the libpq dynamic library used at runtime. You can avoid the problem by using the same version of the :program:`pg_config` at install time and the libpq at runtime. diff --git a/doc/src/usage.rst b/doc/src/usage.rst index b87887d1..5cd4a0d7 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -899,6 +899,18 @@ using the |lo_import|_ and |lo_export|_ libpq functions. .. |lo_export| replace:: `!lo_export()` .. _lo_export: http://www.postgresql.org/docs/current/static/lo-interfaces.html#LO-EXPORT +.. versionchanged:: 2.6 + added support for large objects greated than 2GB. Note that the support is + enabled only if both these conditions are verified: + + - the extension was built against libpq at least 9.3 (you can check if + `psycopg2.__version__` contains the ``lo64`` flag); + - the server version is at least PostgreSQL 9.3 + (`~connection.server_version` must be >= ``90300``). + + If the contitions are not met several `!lobject` methods will fail if the + arguments exceed 2GB. + .. index::