Convert PGconn, PGresult to opaque types?

In last week's episode, I wrote:

I have dealt with this by splitting libpq-fe.h into two files, leaving
only exportable information in libpq-fe.h and moving the internals into
a new file libpq-int.h. This should solve Ewan's problem and reduce
application-code namespace pollution in general.

(If I were really being fascist about this I would've moved the
definitions of struct pg_conn and friends into libpq-int.h, leaving
only an opaque "struct pg_conn" declaration to be seen by applications.
But I'm afraid that that will break too many applications. Perhaps we
can take that step in some future release.)

Today I am wondering whether it wouldn't be a good idea to just go ahead
and move those struct declarations into libpq-int.h. Then a pointer to
PGconn would be truly an opaque type for applications; all they'd see is

typedef struct pg_conn * PGconn;

Basically this would force applications to use the accessor functions
as recommended in the documentation, and not touch fields of a PGconn
object directly. (Ditto for PGresult.)

I am scared about external stuff like php. If they use it, and we
release something that doesn't work with their stuff, we are cooked
until they upgrade.

Not really sure what the advantage would be, aside from cleanliness.

I think it is a real good idea to do this eventually, because it will
help ensure that applications don't assume things they shouldn't about
what is in a PGconn, and it will allow us to modify the PGconn structure
without breaking binary compatibility of applications across libpq
releases. This is a critical consideration now that libpq is released
as a shared library on Unix and will be available in DLL form for
Windows. People tend to think that they can update shared libraries
without recompiling the programs that use the libraries.

What occurs to me today is that if we intend to do it eventually, we
may as well do it *now*. Waiting will just give more programmers the
opportunity to write bad code, I think. And we are going to break
binary compatibility of libpq in 6.4 anyway --- the contents of PGconn
have changed since last time. So anyone who's not relying on the
accessor functions is already in trouble.

The downside is that we will probably break at least some applications
at source-code level. They weren't playing by the rules, but they'll
be annoyed anyway. (Anyone who's too lazy to fix their code can just
import libpq-int.h instead of libpq-fe.h, but one hopes not too many
people will take that way out.)

I know that both psql and libpgtcl are not playing entirely by the rules,
and will need to be fixed. I can handle that. I'm not volunteering
to fix any code outside the distribution, however.

Comments? Any strong reasons *not* to do this?

regards, tom lane

-- 
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)

Bruce Momjian wrote:

Basically this would force applications to use the accessor functions
as recommended in the documentation, and not touch fields of a PGconn
object directly. (Ditto for PGresult.)

I am scared about external stuff like php. If they use it, and we
release something that doesn't work with their stuff, we are cooked
until they upgrade.

Not really sure what the advantage would be, aside from cleanliness.

The cleaness allows us to change the interals without breaking "external
stuff".
I think Tom is aiming for thread-safeness which can't be done as long as
external stuff insists on accessing global structs inside libpq.
Sometimes we have to break thing to make them work better.

regards,
--
---------------------------------------------
G�ran Thyni, sysadm, JMS Bildbasen, Kiruna