Re: DBlink documentation

Where do I find documentation for using dblink?

I am running PostgreSQL 8.03 on SuSE 9.3 and I installed the
postgresql-contrib package, but it only includes the README for dblink,
which only lists the functions, but it does not include any information
on how to use it.

For instance, it would list:

dblink_connect(text) RETURNS text.

But what should 'text' be?

I searched through the Postgres site and mailing list archives and I get
a lot of references of "look in the dblink documentation".
Unfortunately I have have not yet been able to find this documentation?

Can anybody please give me a link to the documentation?

Thanks
--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ A dinosaur is a salamander designed to Mil Spec ~

Andre Truter wrote:

>Where do I find documentation for using dblink?
>
>I am running PostgreSQL 8.03 on SuSE 9.3 and I installed the
>postgresql-contrib package, but it only includes the README for dblink,
>which only lists the functions, but it does not include any information
>on how to use it.
>
>For instance, it would list:
>
>dblink_connect(text) RETURNS text.
>
>But what should 'text' be?
>
>I searched through the Postgres site and mailing list archives and I get
>a lot of references of "look in the dblink documentation".
>Unfortunately I have have not yet been able to find this documentation?
>
>Can anybody please give me a link to the documentation?
>
>Thanks
>
>

It's on the contrib package
or in the contrib dir if you installed from source

leonel

On Sat, 2005-12-17 at 06:20 -0700, Leonel Nunez wrote:

>
> It's on the contrib package

No, unfortunately the SUSE people did not include it in the contrib
package.

> or in the contrib dir if you installed from source
>
Installed from rpm package.
I have searched for the dblink source to get the docs from there, but I
have also failed to find it so far.
Maybe I am searching wrong?

I searched the Postgres site for 'dblink source'

--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ "Oh Bother!" said the Borg, "We assimilated the Pooh!" ~

Andre Truter wrote:

>On Sat, 2005-12-17 at 06:20 -0700, Leonel Nunez wrote:
>
>
>
>>It's on the contrib package
>>
>>
>
>No, unfortunately the SUSE people did not include it in the contrib
>package.
>
>
>
>>or in the contrib dir if you installed from source
>>
>>
>>
>Installed from rpm package.
>I have searched for the dblink source to get the docs from there, but I
>have also failed to find it so far.
>Maybe I am searching wrong?
>
>I searched the Postgres site for 'dblink source'
>
>
>

download the source for your PostgreSQL version unpackit
and check on the contrib/dblink dir

leonel

On Sat, 2005-12-17 at 07:04 -0700, Leonel Nunez wrote:

> download the source for your PostgreSQL version unpackit
> and check on the contrib/dblink dir
>

Yes, that is what I have been trying to do, but where do I download the
dblink source from?

--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ A dinosaur is a salamander designed to Mil Spec ~

Andre Truter <linux(at)trusoft(dot)co(dot)za> writes:

> On Sat, 2005-12-17 at 07:04 -0700, Leonel Nunez wrote:
>
>> download the source for your PostgreSQL version unpackit
>> and check on the contrib/dblink dir
>>
>
> Yes, that is what I have been trying to do, but where do I download the
> dblink source from?

That's what he's trying to tell you--it's in the 'contrib' directory
of the main source tarball.

-Doug

On Sat, 17 Dec 2005 08:21:29 -0600, Douglas McNaught <doug(at)mcnaught(dot)org>
wrote:

> Andre Truter <linux(at)trusoft(dot)co(dot)za> writes:
>
>> On Sat, 2005-12-17 at 07:04 -0700, Leonel Nunez wrote:
>>
>>> download the source for your PostgreSQL version unpackit
>>> and check on the contrib/dblink dir
>>>
>>
>> Yes, that is what I have been trying to do, but where do I download the
>> dblink source from?
>
> That's what he's trying to tell you--it's in the 'contrib' directory
> of the main source tarball.
>

Is the documentation not available online somewhere?

--

Russ

"Russ Brown" <pickscrape(at)gmail(dot)com> writes:

> Is the documentation not available online somewhere?

For the stuff in 'contrib', I don't think so. Might be a good project
for someone. :)

-Doug

On Sat, 2005-12-17 at 09:21 -0500, Douglas McNaught wrote:
> Andre Truter <linux(at)trusoft(dot)co(dot)za> writes:
>
> > On Sat, 2005-12-17 at 07:04 -0700, Leonel Nunez wrote:
> >
> >> download the source for your PostgreSQL version unpackit
> >> and check on the contrib/dblink dir
> >>
> >
> > Yes, that is what I have been trying to do, but where do I download the
> > dblink source from?
>
> That's what he's trying to tell you--it's in the 'contrib' directory
> of the main source tarball.
>

Ah! I misunderstood.
I expected the dblink or contrib stuff to be a separate project, not
part of the postgres source tree.

That explain why I could not find it.

Thanks, I'll download the Posgres source then.

I would be nice if the documentation could be online though, then I
would not need to download the whole postgres source just to get the
documentation for one small part.

Or, is there a CVS browser available, so I can only checkout/download
the dblink stuff?
(Bandwidth is a problem for me at the moment)

--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ "Oh Bother!" said the Borg, "We assimilated the Pooh!" ~

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

> Is the documentation not available online somewhere?

Quick version for you:

http://www.gtsm.com/dblink/

- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200512170951
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iD8DBQFDpCYXvJuQZxSWSsgRAgGtAKDk9H/KFCjNjdaxGaPQkqdYzLITwACglSQt
cG2yNm8kVfsiqE4DcPVZOpQ=
=9YZG
-----END PGP SIGNATURE-----

On Sat, 2005-12-17 at 14:53 +0000, Greg Sabino Mullane wrote:

> > Is the documentation not available online somewhere?
>
> Quick version for you:
>
> http://www.gtsm.com/dblink/
>
>

Great!
This is exactly what I want.

Thanks Greg!

--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ A dinosaur is a salamander designed to Mil Spec ~

Am Samstag, den 17.12.2005, 16:53 +0200 schrieb Andre Truter:
...
> Thanks, I'll download the Posgres source then.
>
> I would be nice if the documentation could be online though, then I
> would not need to download the whole postgres source just to get the
> documentation for one small part.

This is understandable ;) But in this case not postgres peoples
fault. There is no reason a package manager should exclude parts
of the software at will. The complete software includes all you need.
Well done packages either have a big package of all or single packages
you install which include the documentation too.
If someone does not use a package, (s)he is downloading the source
anyway to get postgres :-)

Regards
Tino

On Sat, 2005-12-17 at 17:09 +0100, Tino Wildenhain wrote:

>
> This is understandable ;) But in this case not postgres peoples
> fault.

Yes, I realise it is not the fault of the postgres people and I did not
intend to make it sound like that.

I am a bit disappointed that the rpm package that comes with SuSE does
not include all the docs.
I will mention this on the SuSE mailing list.

--
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ "Oh Bother!" said the Borg, "We assimilated the Pooh!" ~

Tino Wildenhain <tino(at)wildenhain(dot)de> writes:
> Am Samstag, den 17.12.2005, 16:53 +0200 schrieb Andre Truter:
>> I would be nice if the documentation could be online though, then I
>> would not need to download the whole postgres source just to get the
>> documentation for one small part.

> This is understandable ;) But in this case not postgres peoples
> fault. There is no reason a package manager should exclude parts
> of the software at will.

Actually, I don't think you can reasonably blame the Debian packager
for having overlooked the fact that contrib/dblink has more
documentation files besides its README. The PGDG RPM people overlooked
that too, as did Red Hat (ie, me).

Now that I look, tsearch2 has also adopted a nonstandard documentation
layout.

While we (the packagers) could fix this now that our attention has been
called to it, I wonder whether the better plan wouldn't be to insist
that dblink and tsearch2 fall into line with the rest of the contrib
modules. At the very least we need a uniform convention for docs files
so that packagers won't be playing catchup forever.

regards, tom lane

Tom Lane wrote:
> Actually, I don't think you can reasonably blame the Debian packager
> for having overlooked the fact that contrib/dblink has more
> documentation files besides its README. The PGDG RPM people overlooked
> that too, as did Red Hat (ie, me).

Well, in my own defense, I pointed out the change explicitly when I
submitted the patch (which was over 3 years ago now, prior to 7.3 beta
feature freeze), and no one objected back then:
http://archives.postgresql.org/pgsql-patches/2002-08/msg00640.php

> While we (the packagers) could fix this now that our attention has been
> called to it, I wonder whether the better plan wouldn't be to insist
> that dblink and tsearch2 fall into line with the rest of the contrib
> modules. At the very least we need a uniform convention for docs files
> so that packagers won't be playing catchup forever.

I'm happy to lump all the docs back into the README if that's what you
want, but I split it up in the first place because it was getting very long.

Joe

Joe Conway <mail(at)joeconway(dot)com> writes:
> I'm happy to lump all the docs back into the README if that's what you
> want, but I split it up in the first place because it was getting very long.

No, I'm not really proposing that we force all contrib modules to have
only a README. I'm just annoyed by the lack of consistency (dblink/doc
versus tsearch2/docs, and some of the other modules seem to have some
doc files just loose in their top directory).

It's not only the downstream packagers that have missed these: the
Makefiles don't install them either.

It'd be a good idea to settle on what we want the installed file layout
to be --- do we need to create subdirectories under {prefix}/doc to
forestall name conflicts?

regards, tom lane

Tom Lane wrote:
> Joe Conway <mail(at)joeconway(dot)com> writes:
> > I'm happy to lump all the docs back into the README if that's what you
> > want, but I split it up in the first place because it was getting very long.
>
> No, I'm not really proposing that we force all contrib modules to have
> only a README. I'm just annoyed by the lack of consistency (dblink/doc
> versus tsearch2/docs, and some of the other modules seem to have some
> doc files just loose in their top directory).
>
> It's not only the downstream packagers that have missed these: the
> Makefiles don't install them either.
>
> It'd be a good idea to settle on what we want the installed file layout
> to be --- do we need to create subdirectories under {prefix}/doc to
> forestall name conflicts?

I personally never saw those doc/ files when I was modifying dblink. I
had to grope around in the regression tests to see how the functions
worked.

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073

On 12/17/2005 08:33:02 AM, Russ Brown wrote:

> Is the documentation not available online somewhere?

There is always the CVS web interface:
http://developer.postgresql.org/cvsweb.cgi/pgsql/

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On Sat, Dec 17, 2005 at 03:47:54PM -0500, Tom Lane wrote:
> It'd be a good idea to settle on what we want the installed file layout
> to be --- do we need to create subdirectories under {prefix}/doc to
> forestall name conflicts?

README is probably fine for most of what's in contrib, but for other
stuff we should support a doc directory. tsearch2 currently has 100k of
HTML in docs, I really don't think we want to cram all that into the
README.
--
Jim C. Nasby, Sr. Engineering Consultant jnasby(at)pervasive(dot)com
Pervasive Software http://pervasive.com work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461

Tom Lane wrote:
> Joe Conway <mail(at)joeconway(dot)com> writes:
>
>>I'm happy to lump all the docs back into the README if that's what you
>>want, but I split it up in the first place because it was getting very long.
>
> No, I'm not really proposing that we force all contrib modules to have
> only a README. I'm just annoyed by the lack of consistency (dblink/doc
> versus tsearch2/docs, and some of the other modules seem to have some
> doc files just loose in their top directory).
>
> It's not only the downstream packagers that have missed these: the
> Makefiles don't install them either.
>
> It'd be a good idea to settle on what we want the installed file layout
> to be --- do we need to create subdirectories under {prefix}/doc to
> forestall name conflicts?
>

While I'm messing with dblink, did you want me to do anything WRT this?

Thanks,

Joe

Joe Conway <mail(at)joeconway(dot)com> writes:
> Tom Lane wrote:
>> It's not only the downstream packagers that have missed these: the
>> Makefiles don't install them either.
>>
>> It'd be a good idea to settle on what we want the installed file layout
>> to be --- do we need to create subdirectories under {prefix}/doc to
>> forestall name conflicts?

> While I'm messing with dblink, did you want me to do anything WRT this?

I don't think we settled on what we want to do yet. Any thoughts?

I'm kind of leaning toward the subdirectory idea myself...

regards, tom lane

Tom Lane wrote:
> Joe Conway <mail(at)joeconway(dot)com> writes:
>>Tom Lane wrote:
>>
>>>It's not only the downstream packagers that have missed these: the
>>>Makefiles don't install them either.
>>>
>>>It'd be a good idea to settle on what we want the installed file layout
>>>to be --- do we need to create subdirectories under {prefix}/doc to
>>>forestall name conflicts?
>
>>While I'm messing with dblink, did you want me to do anything WRT this?
>
> I don't think we settled on what we want to do yet. Any thoughts?
>
> I'm kind of leaning toward the subdirectory idea myself...

(I removed GENERAL, and added DOCS to the distribution of this thread)

Well I like {prefix}/doc given that's how dblink is already set up ;-)

Questions:
- Do we want a naming convention for the files in
{prefix}/doc?
- Do we pre-create {prefix}/doc for every contrib
directory in advance?

I think the answers are no, and yes, but I don't feel strongly about either.

Joe

On Tue, Jan 03, 2006 at 04:20:38PM -0800, Joe Conway wrote:
> Tom Lane wrote:
> >Joe Conway <mail(at)joeconway(dot)com> writes:
> >>Tom Lane wrote:
> >>
> >>>It's not only the downstream packagers that have missed these: the
> >>>Makefiles don't install them either.
> >>>
> >>>It'd be a good idea to settle on what we want the installed file layout
> >>>to be --- do we need to create subdirectories under {prefix}/doc to
> >>>forestall name conflicts?
> >
> >>While I'm messing with dblink, did you want me to do anything WRT this?
> >
> >I don't think we settled on what we want to do yet. Any thoughts?
> >
> >I'm kind of leaning toward the subdirectory idea myself...
>
> (I removed GENERAL, and added DOCS to the distribution of this thread)
>
> Well I like {prefix}/doc given that's how dblink is already set up ;-)
>
> Questions:
> - Do we want a naming convention for the files in
> {prefix}/doc?
> - Do we pre-create {prefix}/doc for every contrib
> directory in advance?
>
> I think the answers are no, and yes, but I don't feel strongly about either.

By {prefix} do you mean where PostgreSQL is being installed? If so, that
would be highly non-standard. I think what you'd want is
{prefix}/share/doc/postgresql/contrib/.
--
Jim C. Nasby, Sr. Engineering Consultant jnasby(at)pervasive(dot)com
Pervasive Software http://pervasive.com work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461

Jim C. Nasby wrote:
> On Tue, Jan 03, 2006 at 04:20:38PM -0800, Joe Conway wrote:
>>Well I like {prefix}/doc given that's how dblink is already set up ;-)
>>

> By {prefix} do you mean where PostgreSQL is being installed? If so, that
> would be highly non-standard. I think what you'd want is
> {prefix}/share/doc/postgresql/contrib/.

Well, I assumed Tom was referring to placement in the source tree, i.e.
{prefix} is contrib/dblink, etc.

But this raises a good question in terms of where these files should be
installed. The README.xxx files all go to {install-prefix}/doc/contrib.
I experimented with changing the Makefile line:
DOCS = README.dblink
to be:
DOCS = README.dblink doc/*

Unfortunately the files from contrib/dblink/doc still wound up being
installed to {install-prefix}/doc/contrib, which would become a naming
collision hazard. Maybe they should go to
{install-prefix}/doc/contrib/xxx (where xxx is the name of each contrib
dir)?

Joe

Joe Conway <mail(at)joeconway(dot)com> writes:
> Well, I assumed Tom was referring to placement in the source tree, i.e.
> {prefix} is contrib/dblink, etc.

I'm concerned about both location in the source tree (dblink and
tsearch2 are inconsistent) and location in the installation tree.
The former seems easy to resolve: doc/ is the universal standard
directory name for documentation, not docs/. I am not sure that
we want to commit to creating a pile of subdirectories under the
installation doc/ directory, though. If they were mostly full,
fine, but a bunch of directories that are mostly empty would just
be clutter. Maybe create subdirectories only for modules that
have 'em in the source tree?

regards, tom lane