summaryrefslogtreecommitdiff
path: root/doc/src/sgml/lobj.sgml
AgeCommit message (Collapse)Author
2025-03-25libpq: Deprecate pg_int64.Thomas Munro
Previously we used pg_int64 in three function prototypes in libpq. It was added by commit 461ef73f to expose the platform-dependent type used for int64 in the C89 era. As of commit 962da900 it is defined as standard int64_t, and the dust seems to have settled. Let's just use int64_t directly in these three client-facing functions instead of (yet) another name. We've required C99 and thus <stdint.h> since PostgreSQL 12, C89 and C++98 compilers are long gone, and client applications very likely use standard types for their own 64-bit needs. This also cleans up the obscure placement of a new #include <stdint.h> directive in postgres_ext.h, required for the new definition. The typedef was hiding in there for historical reasons, but it doesn't fit postgres_ext.h's own description of its purpose and there is no evidence of client applications including postgres_ext.h directly to see it. Keep a typedef marked deprecated for backward compatibility, but move it into libpq-fe.h where it was used. Reviewed-by: Peter Eisentraut <[email protected]> Discussion: https://postgr.es/m/CA%2BhUKGKn_EkNNGMY5RzMcKP%2Ba6urT4JF%3DCPhw_zHtQwjvX6P2g%40mail.gmail.com
2025-01-01Update copyright for 2025Bruce Momjian
Backpatch-through: 13
2024-01-04Update copyright for 2024Bruce Momjian
Reported-by: Michael Paquier Discussion: https://postgr.es/m/[email protected] Backpatch-through: 12
2023-01-02Update copyright for 2023Bruce Momjian
Backpatch-through: 11
2022-07-04Prevent write operations on large objects in read-only transactionsMichael Paquier
Attempting such an operation would already fail, but in various and confusing ways. For example, while in recovery, some elog() messages would be reported, but these should never be user-facing. This commit restricts any write operations done on large objects in a read-only context, so as the errors generated are more user-friendly. This is per the discussion done with Tom Lane and Robert Haas. Some regression tests are added to check the case of all the SQL functions working on large objects (including an update of the test's alternate output). Author: Yugo Nagata Discussion: https://postgr.es/m/[email protected]
2022-02-01Doc: modernize documentation for lo_create()/lo_creat().Tom Lane
At this point lo_creat() is a legacy function with little if any real use-case, so describing it first doesn't make much sense. Describe lo_create() first, and then explain lo_creat() as a backwards-compatibility alternative. Discussion: https://postgr.es/m/[email protected]
2022-01-08Update copyright for 2022Bruce Momjian
Backpatch-through: 10
2021-09-19Doc: fix typos.Tom Lane
"PGcon" should be "PGconn". Noted by D. Frey. Discussion: https://postgr.es/m/[email protected]
2021-03-15Implement pipeline mode in libpqAlvaro Herrera
Pipeline mode in libpq lets an application avoid the Sync messages in the FE/BE protocol that are implicit in the old libpq API after each query. The application can then insert Sync at its leisure with a new libpq function PQpipelineSync. This can lead to substantial reductions in query latency. Co-authored-by: Craig Ringer <[email protected]> Co-authored-by: Matthieu Garrigues <[email protected]> Co-authored-by: Álvaro Herrera <[email protected]> Reviewed-by: Andres Freund <[email protected]> Reviewed-by: Aya Iwata <[email protected]> Reviewed-by: Daniel Vérité <[email protected]> Reviewed-by: David G. Johnston <[email protected]> Reviewed-by: Justin Pryzby <[email protected]> Reviewed-by: Kirk Jamison <[email protected]> Reviewed-by: Michael Paquier <[email protected]> Reviewed-by: Nikhil Sontakke <[email protected]> Reviewed-by: Vaishnavi Prabakaran <[email protected]> Reviewed-by: Zhihong Yu <[email protected]> Discussion: https://postgr.es/m/CAMsr+YFUjJytRyV4J-16bEoiZyH=4nj+sQ7JP9ajwz=B4dMMZw@mail.gmail.com Discussion: https://postgr.es/m/CAJkzx4T5E-2cQe3dtv2R78dYFvz+in8PY7A8MArvLhs_pg75gg@mail.gmail.com
2021-01-22Avoid redundantly prefixing PQerrorMessage for a connection failure.Tom Lane
libpq's error messages for connection failures pretty well stand on their own, especially since commits 52a10224e/27a48e5a1. Prefixing them with 'could not connect to database "foo"' or the like is just redundant, and perhaps even misleading if the specific database name isn't relevant to the failure. (When it is, we trust that the backend's error message will include the DB name.) Indeed, psql hasn't used any such prefix in a long time. So, make all our other programs and documentation examples agree with psql's practice. Discussion: https://postgr.es/m/[email protected]
2021-01-02Update copyright for 2021Bruce Momjian
Backpatch-through: 9.5
2020-09-24Doc: sync lobj.sgml's copy of testlo.c with the latter file.Tom Lane
Zhijie Hou Discussion: https://postgr.es/m/ce2cd951fe9b448a9cda99dc1a871fb9@G08CNEXMBPEKD05.g08.fujitsu.local
2020-05-10Doc: marginal hacking to remove some PDF build warnings.Tom Lane
This patch eliminates a few more "exceed the available area" warnings whose causes aren't particularly connected to anything else. The only one really worthy of comment is that I increased the space allowed for an <orderedlist>'s numbers, because the default of 1em doesn't quite work for more than one digit. The rest are one-off insertions of &zwsp; and suchlike tweaks, in places where they shouldn't do any damage to the material. (In particular, although I split some long identifiers with zwsp's, there are other nearby occurrences of each one; so those changes shouldn't hurt greppability of the document sources.)
2020-05-07Doc: update remaining tables of functions/operators for new layout.Tom Lane
This converts the contrib documentation to the new style, and mops up a couple of function tables that were outside chapter 9 in the main docs. A few contrib modules choose not to present their functions in the standard tabular format. There might be room to rethink those decisions now that the standard format is more friendly to verbose descriptions. But I have not undertaken to do that here; I just converted existing tables.
2020-01-01Update copyrights for 2020Bruce Momjian
Backpatch-through: update all files in master, backpatch legal files through 9.4
2019-09-08doc: Clean up title case usePeter Eisentraut
Note: Following existing practice, titles of formalpara and step are not titlecased.
2019-07-26doc: Make libpq documentation navigable between functionsPeter Eisentraut
Turn most mentions of libpq functions into links. At id attributes to most libpq functions, where not existing yet, so that they can be linked to. (In a handful of cases there were problems with the PDF processing toolchain, so those instances were not changed.) Author: Fabien COELHO <[email protected]> Reviewed-by: Peter Eisentraut <[email protected]> Discussion: https://www.postgresql.org/message-id/flat/alpine.DEB.2.21.1905121032330.27203@lancre
2019-01-02Update copyright for 2019Bruce Momjian
Backpatch-through: certain files through 9.4
2018-11-02Fix some spelling errors in the documentationMagnus Hagander
Author: Daniel Gustafsson <[email protected]>
2018-09-21docs: remove use of escape strings and use bytea hex outputBruce Momjian
standard_conforming_strings defaulted to 'on' in PG 9.1. bytea_output defaulted to 'hex' in PG 9.0. Reported-by: André Hänsel Discussion: https://postgr.es/m/[email protected] Backpatch-through: 9.3
2018-07-01Fix libpq example programsPeter Eisentraut
When these programs call pg_catalog.set_config, they need to check for PGRES_TUPLES_OK instead of PGRES_COMMAND_OK. Fix for 5770172cb0c9df9e6ce27c507b449557e5b45124. Reported-by: Ideriha, Takeshi <[email protected]>
2018-02-26Document security implications of search_path and the public schema.Noah Misch
The ability to create like-named objects in different schemas opens up the potential for users to change the behavior of other users' queries, maliciously or accidentally. When you connect to a PostgreSQL server, you should remove from your search_path any schema for which a user other than yourself or superusers holds the CREATE privilege. If you do not, other users holding CREATE privilege can redefine the behavior of your commands, causing them to perform arbitrary SQL statements under your identity. "SET search_path = ..." and "SELECT pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one can use either as the first command of a session. As special exceptions, the following client applications behave as documented regardless of search_path settings and schema privileges: clusterdb createdb createlang createuser dropdb droplang dropuser ecpg (not programs it generates) initdb oid2name pg_archivecleanup pg_basebackup pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb vacuumlo. Not included are core client programs that run user-specified SQL commands, namely psql and pgbench. PostgreSQL encourages non-core client applications to do likewise. Document this in the context of libpq connections, psql connections, dblink connections, ECPG connections, extension packaging, and schema usage patterns. The principal defense for applications is "SELECT pg_catalog.set_config('search_path', '', false)", and the principal defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC". Either one is sufficient to prevent attack. After a REVOKE, consider auditing the public schema for objects named like pg_catalog objects. Authors of SECURITY DEFINER functions use some of the same defenses, and the CREATE FUNCTION reference page already covered them thoroughly. This is a good opportunity to audit SECURITY DEFINER functions for robust security practice. Back-patch to 9.3 (all supported versions). Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy Sharoglazov. Security: CVE-2018-1058
2018-01-03Update copyright for 2018Bruce Momjian
Backpatch-through: certain files through 9.3
2017-11-23Convert documentation to DocBook XMLPeter Eisentraut
Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-14Document changes in large-object privilege checking.Tom Lane
Commit 5ecc0d738 removed the hard-wired superuser checks in lo_import and lo_export in favor of protecting them with SQL permissions, but failed to adjust the documentation to match. Fix that, and add a <caution> paragraph pointing out the nontrivial security hazards involved with actually granting such permissions. (It's still better than ALLOW_DANGEROUS_LO_FUNCTIONS, though.) Also, commit ae20b23a9 caused large object read/write privilege to be checked during lo_open() rather than in the actual read or write calls. Document that. Discussion: https://postgr.es/m/CAB7nPqRHmNOYbETnc_2EjsuzSM00Z+BWKv9sy6tnvSd5gWT_JA@mail.gmail.com
2017-10-20Convert SGML IDs to lower casePeter Eisentraut
IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <[email protected]>
2017-10-17Don't use SGML empty tagsPeter Eisentraut
For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-01-03Update copyright via script for 2017Bruce Momjian
2016-08-05docs: re-add spaces before units removedBruce Momjian
This reverts the spaces before k/M/G/TB units removed for consistency in commit ca0c37b56f4a80ad758774e34c86cc4335583d29. Discussion: [email protected]
2016-07-30docs: properly capitalize and space kB, MB, GB, TBBruce Momjian
2016-01-02Update copyright for 2016Bruce Momjian
Backpatch certain files through 9.1
2015-01-06Update copyright for 2015Bruce Momjian
Backpatch certain files through 9.0
2014-06-12Rename lo_create(oid, bytea) to lo_from_bytea().Tom Lane
The previous naming broke the query that libpq's lo_initialize() uses to collect the OIDs of the server-side functions it requires, because that query effectively assumes that there is only one function named lo_create in the pg_catalog schema (and likewise only one lo_open, etc). While we should certainly make libpq more robust about this, the naive query will remain in use in the field for the foreseeable future, so it seems the only workable choice is to use a different name for the new function. lo_from_bytea() won a small straw poll. Back-patch into 9.4 where the new function was introduced.
2014-01-07Update copyright for 2014Bruce Momjian
Update all files in head, and files COPYRIGHT and legal.sgml in all back branches.
2013-10-28Suppress duplicate-index-entry warning introduced by previous commit.Tom Lane
We don't need two index entries for lo_create pointing at the same section. It's a bit pedantic for the toolchain to warn about this, but warn it does.
2013-10-28Add large object functions catering to SQL callers.Noah Misch
With these, one need no longer manipulate large object descriptors and extract numeric constants from header files in order to read and write large object contents from SQL. Pavel Stehule, reviewed by Rushabh Lathia.
2013-09-11docs: Update libpq and testlo examplesBruce Momjian
Josh Kupershmidt
2013-06-12Improve description of loread/lowrite.Robert Haas
Patch by me, reviewed by Tatsuo Ishii.
2013-06-11Add description that loread()/lowrite() are corresponding toTatsuo Ishii
lo_read()/lo_write() in libpq to avoid confusion.
2012-10-09Fix lo_read, lo_write, lo_truncate to cope with "size_t" length parameters.Tom Lane
libpq defines these functions as accepting "size_t" lengths ... but the underlying backend functions expect signed int32 length parameters, and so will misinterpret any value exceeding INT_MAX. Fix the libpq side to throw error rather than possibly doing something unexpected. This is a bug of long standing, but I doubt it's worth back-patching. The problem is really pretty academic anyway with lo_read/lo_write, since any caller expecting sane behavior would have to have provided a multi-gigabyte buffer. It's slightly more pressing with lo_truncate, but still we haven't supported large objects over 2GB until now.
2012-10-07Improve documentation about large-object functions.Tom Lane
Copy-editing for previous patch, plus fixing some longstanding markup issues and oversights (like not mentioning that failures will set the PQerrorMessage string).
2012-10-06Add API for 64-bit large object access. Now users can access up toTatsuo Ishii
4TB large objects (standard 8KB BLCKSZ case). For this purpose new libpq API lo_lseek64, lo_tell64 and lo_truncate64 are added. Also corresponding new backend functions lo_lseek64, lo_tell64 and lo_truncate64 are added. inv_api.c is changed to handle 64-bit offsets. Patch contributed by Nozomi Anzai (backend side) and Yugo Nagata (frontend side, docs, regression tests and example program). Reviewed by Kohei Kaigai. Committed by Tatsuo Ishii with minor editings.
2011-03-11In docs, rename "backwards compatibility" to "backward compatibility"Bruce Momjian
for consistency.
2011-02-07Implement genuine serializable isolation level.Heikki Linnakangas
Until now, our Serializable mode has in fact been what's called Snapshot Isolation, which allows some anomalies that could not occur in any serialized ordering of the transactions. This patch fixes that using a method called Serializable Snapshot Isolation, based on research papers by Michael J. Cahill (see README-SSI for full references). In Serializable Snapshot Isolation, transactions run like they do in Snapshot Isolation, but a predicate lock manager observes the reads and writes performed and aborts transactions if it detects that an anomaly might occur. This method produces some false positives, ie. it sometimes aborts transactions even though there is no anomaly. To track reads we implement predicate locking, see storage/lmgr/predicate.c. Whenever a tuple is read, a predicate lock is acquired on the tuple. Shared memory is finite, so when a transaction takes many tuple-level locks on a page, the locks are promoted to a single page-level lock, and further to a single relation level lock if necessary. To lock key values with no matching tuple, a sequential scan always takes a relation-level lock, and an index scan acquires a page-level lock that covers the search key, whether or not there are any matching keys at the moment. A predicate lock doesn't conflict with any regular locks or with another predicate locks in the normal sense. They're only used by the predicate lock manager to detect the danger of anomalies. Only serializable transactions participate in predicate locking, so there should be no extra overhead for for other transactions. Predicate locks can't be released at commit, but must be remembered until all the transactions that overlapped with it have completed. That means that we need to remember an unbounded amount of predicate locks, so we apply a lossy but conservative method of tracking locks for committed transactions. If we run short of shared memory, we overflow to a new "pg_serial" SLRU pool. We don't currently allow Serializable transactions in Hot Standby mode. That would be hard, because even read-only transactions can cause anomalies that wouldn't otherwise occur. Serializable isolation mode now means the new fully serializable level. Repeatable Read gives you the old Snapshot Isolation level that we have always had. Kevin Grittner and Dan Ports, reviewed by Jeff Davis, Heikki Linnakangas and Anssi Kääriäinen
2011-02-01Properly capitalize hyphenated words in documentation titles.Bruce Momjian
2010-11-23Remove useless whitespace at end of linesPeter Eisentraut
2010-09-20Remove cvs keywords from all files.Magnus Hagander
2010-08-10Use double quotes rather than double quotes for libpq target anchors.Robert Haas
Per observation from Tom Lane that the previous patch to these files was not consistent with what is done elsewhere in the docs.
2010-08-09Provide stable target anchors for libpq functions.Robert Haas
Daniele Varrazzo
2010-04-03Remove unnecessary xref endterm attributes and title idsPeter Eisentraut
The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-16 03:15:54 +0000