David,
That said, I am curious as to the education flow a developer, not linking in 
this specific header to their code, would go through in order to learn about 
type OIDs and make use of them in their project.  Maybe that flow is good, 
maybe not.  It's a rare flow and there are many things to do in the project.  
So my curiosity may not get satiated.  As you brought this up and are invested 
in the outcome you have more motivation than probably anyone else to dive into 
it and make concrete suggestions for change.

Any project using the PostgreSQL C API to implement an interface/module for 
another programming language will need to implement basic SQL handling 
functions to prepare, execute, fetch rows, AND introspect SQL statements parts 
like column information (name, type).

We have for ex a SQL handler class in Genero BDL, providing following methods:

  DEFINE h base.SqlHandle
  LET h = base.SqlHandle.create()
  CALL h.prepare("SELECT ....")
  CALL h.open()
  DISPLAY h.getResultType(1) : type name of column #1
  DISPLAY h.getResultType(2) : type name of column #2
  ...


About the PQftype() doc, the header file catalog/pg_type_d.h is mentioned, but 
I think it is missing the fact that type OID constants can be recognized in 
that header file, with the "OID" suffix.

While I understand that it's additional work on doc maintenance, I would in 
fact expect an exhaustive list of built-in data type ids just like in:

https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/sql-data-types?view=sql-server-ver16

https://dev.mysql.com/doc/c-api/8.4/en/c-api-prepared-statement-type-codes.html

https://www.ibm.com/docs/en/informix-servers/15.0.0?topic=constants-sql-data-type#ids_esqlc_0123__sii-03-97666

But I can understand that this is maybe not natural for PostgreSQL 
implementors, because of the flexible data type system and the fact that even 
built-in type ids are generated.

Seb





________________________________
From: David G. Johnston <david.g.johns...@gmail.com>
Sent: Thursday, March 20, 2025 5:25 PM
To: Sebastien Flaesch <sebastien.flae...@4js.com>
Cc: Tom Lane <t...@sss.pgh.pa.us>; Adrian Klaver <adrian.kla...@aklaver.com>; M 
Tarkeshwar Rao <m.tarkeshwar....@ericsson.com>; pgsql-gene...@postgresql.org 
<pgsql-gene...@postgresql.org>
Subject: Re: After upgrading libpq, the same function(PQftype) call returns a 
different OID


EXTERNAL: Do not click links or open attachments if you do not recognize the 
sender.

On Thu, Mar 20, 2025 at 8:42 AM Sebastien Flaesch 
<sebastien.flae...@4js.com<mailto:sebastien.flae...@4js.com>> wrote:

/*
 * Backwards compatibility for ancient random spellings of pg_type OID macros.
 * Don't use these names in new code.
 */
#define CASHOID MONEYOID
#define LSNOID  PG_LSNOID

#define BOOLOID 16
#define BYTEAOID 17
#define CHAROID 18
#define NAMEOID 19
#define INT8OID 20
#define INT2OID 21
#define INT2VECTOROID 22
#define INT4OID 23
#define REGPROCOID 24

If I am missing something, then please point me to the correct .h file that 
contains #define constants without this scary comment.

OR.... ( I guess I start to understand the code... ) it this comment only for:

Yes, that blank line separating LSNOID and BOOLOID blocks the comment from 
applying to the items after the blank line.  That is a fairly common 
convention, using whitespace to break things up.  Also, assigning one macro to 
another is quite distinct from assigning a constant to a name; making the 
"backward compatibility" aspect of this comment only meaningfully apply to 
those two items.


And sorry if I consider constant names like these (without any prefix such as 
PG_TYPE_)

We spelled PG_TYPE_  as OID and put it on the end.  A boolean as an object is 
by definition a type.  Context clues are important, not every pattern gets 
spelled out in prose.


#define BOOLOID 16
#define BYTEAOID 17
#define CHAROID 18
#define NAMEOID 19
#define INT8OID 20
#define INT2OID 21

Arrogance does not help here, clarity and better API doc would.


To my knowledge the current API doc for this hasn't had any comments of this 
sort for a very long time.  All documentation can be improved because every 
reader comes at it from a different starting point.  Do you have a concrete 
suggestion for what you think should be changed, and why?  My take away from 
this thread is that a single report isn't usually enough to go searching hard 
for ways to tweak the documentation for readability; nor has this one pointed 
out any outright errors to be fixed.  In short, we expect that some subset of 
readers will ask us questions on the mailing list because that is the reality 
of things.

That said, I am curious as to the education flow a developer, not linking in 
this specific header to their code, would go through in order to learn about 
type OIDs and make use of them in their project.  Maybe that flow is good, 
maybe not.  It's a rare flow and there are many things to do in the project.  
So my curiosity may not get satiated.  As you brought this up and are invested 
in the outcome you have more motivation than probably anyone else to dive into 
it and make concrete suggestions for change.

All that said, a comment at the top of what is probably the most important 
section of the header seems warranted.  Even if it is just mostly formality.  
Mentioning the constant-ness of the integers should be part of that.

David J.



Reply via email to