Add sql.describe()

[akheron]

Hi! I'm the author of sqltyper, a tool for automatically creating TypeScript typings for PosgreSQL queries.

One of the things sqltyper does is calling Postgres to describe the input parameters and output columns of a statement. Currently I'm using node-postgres, which doesn't support describing statements. So I've added the support and have an in-tree copy of node-postgres. There's an open PR, but it doesn't seem to move forward.

I would like to use this library for its speed and simplicity instead. Adding support for describing statements didn't require much code, which is nice!

Let me know what you think.

[akheron]

Moved describe to addTypes to make it available in sql.begin. Fixed conflicts.

[TobiasNickel]

@porsager i think this is pretty cool, but should the PR go to version 2.?

[porsager]

Oh man, I'm sorry I haven't had time to look at this, haven't read through it until now.. I think it would a great addition. Your PR looks good, but what do you think about making the API like this:

sql`...`.describe()

That way it's in line with .stream(), .cursor() etc.

[akheron]

Rebased and fixed conflicts 👍

[akheron]

The reason I added it as sql.describe() is that you're not really supposed to use query parameters. If your query requires parameters, you should use $1, $2, etc. directly, so that the query is natively understood by postrges and it can return the type information for $1, $2, etc. In this sense, sql.describe() is closer to sql.file() in my opinion.

[porsager]

@akheron Sorry this has been hanging so long. I've finally found some time for Postgres.js again.. I'd still like if we could have it as sql``.describe() since the query sent is converted to $1, $2 ... anyway. This let's you use .describe with either sql``, sql.unsafe() and sql.file.