Why isn't sslmode=no-verify documented anywhere?

[tgrushka]

Summary

I had to dig everywhere through your repo to find a closed issue that stated I should use ?sslmode=no-verify at the end of my connection string for a hosted PostgreSQL that uses self-signed certificates.

I literally do not have this problem with any other library, so apparently PostGraphile requires SSL verify by default. This is not documented anywhere, nor is it documented how to override it.

I just literally tried out your library today, and it's a great idea, but people will be turned off by lack of documentation and having to dig through library source to figure out what is going on with something so basic that does not present a problem with psql, pgcli, or other library tools (unless the user explicitly specifies they want SSL verification).

It's a great project, but a huge opportunity is missed by not having something very basic like this documented. It's not in the CLI help or args. If designed for postgres, honestly it should work out of the box with the same environment variables and settings that work with psql, pgcli, etc. Large enterprises that would want to use this with extra security (probably not required in most cloud/k8s environments as they are all heavily firewalled by default), their environment vars would call for verification anyway.

Please add docs for this, at the very beginning where people are trying to start it up. Literally would take maybe one line of documentation in the README, and SSL modes mentioned in 5-10 lines in the actual docs.

Otherwise, now that I can connect, I'm looking forward to trying this out and saving me huge headaches I've had trying out another library. I can already tell this has great documentation, just trying to get started.

Thank you.

[benjie]

It's a good question; we should point to the underlying library that does the parsing: https://github.com/brianc/node-postgres/tree/master/packages/pg-connection-string (though for a long time that documentation was incorrect - which is why we didn't link to it - the pg module used to use a different version of the connection string parser which caused different behavior; in Graphile Starter we even have an override to force usage of the correct version so that SSL parsing worked).

I started writing documentation for connection strings for Graphile Worker, and when it's right I plan to port it to our other Postgres-related tools: https://worker.graphile.org/docs/connection-string

If you want to take on the effort of copying this documentation over early, that would be appreciated - contributions to documentation are very much something that the community can contribute to give me time to focus on the more complicated parts needed to get v5.0.0 out the door. Every page in the documentation has an "Edit this page" link you can use to submit suggested edits.

By the way, I would not recommend using no-verify except for testing, you should correctly form your connection string with everything it needs including the SSL details, or use a custom pg.Pool instance passing all the relevant options - you can read more about that in the pg documentation: https://node-postgres.com/apis/pool

If you feel that our connection string behavior is sufficiently different from Postgres' own, then I suggest you raise that with the underlying projects we depend on, most notably pg.

[zubairov]

The importance of issue is hard to undersestimate - keeping in mind that in case of SSL failure many things go wrong unnoticed, like initialisation of database schema and then failing later

[benjie]

How do they go wrong unnoticed? Would it not raise an error?