Use `debug` as default logger

[bas080]

Many tools in the node ecosystem use https://www.npmjs.com/package/debug to make it easy for people to start debugging a certain library in their application.

I can for example do DEBUG='express:*' npm start to get debug information on the express side of things in my app.

It would be neat to be able to do the same for postgres. DEBUG=postgres:* npm start would report on all kinds of events happening during initialization and on queries.

I know I can set a debug callback already.

const debug = require('debug')('postgres:debug')

postgres(process.ENV.DATABASE_URL, {
  debug: (...args) => debug(args)
})

That's what I'm doing currently.

Just trying to suggest a nice default for logging; and yes, my suggestion does add a dependency (downside?).

[bas080]

Here's an example of the output:

  postgres:debug 2 select * from rezerv.reservation
  where
    facility_code = $1
    and (cast($2 as timestamp) is null or reserved_at <= $3) [
  { type: 0, value: 'meeting', raw: 'meeting' },
  { type: 0, value: null, raw: null },
  { type: 0, value: null, raw: null }
] +20ms
  postgres:debug 4 select *
  from rezerv.availability
  where facility_code = $1 [ { type: 0, value: 'meeting', raw: 'meeting' } ] +2ms

It also shows ms since the last reported message which is semi useful information when trying to find a slow running query. Could be better.

[Minigugus]

and yes, my suggestion does add a dependency (downside?).

Not exactly with a peer dependency 😏

if (!options.debug) {
  try {
    options.debug = require('debug')('postgres:debug')
  } catch (err) { /* no debug by default */ }
}

or with the upcoming ESM support:

if (!options.debug) {
  import('debug')
    .then(({ default: debug }) => (options.debug = debug('postgres:debug')))
    .catch(()=>{}) /* no debug by default */
}

[porsager]

I think the fact that it's so simple to add, makes the case to just keep it in userland.

[porsager]

If I'm not wrong, this is enough?

const debug = require('debug')('postgres')

const sql = postgres({
  debug
})

[Minigugus]

Maybe just mentioning this code sample in the README then?

[bas080]

I'm onboard with the conditional dependency approach.

@porsager, not sure what the function signature is of debug callback. I remember noticing it wasn't printing the values. debug only considered the first two arguments.

[bas080]

There is also a reason why postgres.js might want to adopt debug to be able to report on different types of events and ignore others based on provided DEBUG env variable.

[bas080]

@porsager, you are correct. I've checked and it does print all arguments without the need for argument spread.

[s0xDk]

Zero dependencies is one of the major features of this project. And it's a bliss 😇

[porsager]

Agreed ☺️

I'm open to a PR for a debug mention in the docs if anyone feels for it, but I'll close this for now.