feat: add more config examples to CLI

[taimoorzaeem]

Closes #3248.

[wolfgangwalther]

This is not a setting that is possible to set via database configuration. I suggest you go check the code which of those settings are actually possible to set via database config - because there's more than just this that don't make sense here at all.

[wolfgangwalther]

You also have two changes here, one to rename the dump schema cache command and the other to remove --example and -e. Those should probably go into the changed section as well.

[wolfgangwalther]

Seems like you added this - but only in the db settings. I guess we have quite a few settings which are not in those example config files by now, because that's always forgotten when adding a new config.

It would probably be good to go through all of them and add them to all three (two for those with are not db-configurable) examples.

[wolfgangwalther]

Suggested change

	|
	|-- Unix socket location
	|-- if specified it takes precedence over server-port
	|-- ALTER ROLE authenticator SET pgrst.server_unix_socket = '/tmp/pgrst.sock';

This is not in the list of dbSettingsNames.

[taimoorzaeem]

@wolfgangwalther Hmm, I have noticed an inconsistency between docs and dbSettingsNames. The dbSettingsNames include db_tx_end but the docs configuration page says that db_tx_end is n/a for in-db config. More the dbSettingsNames include raw_media_types but there is no detail available around this config in the documentation.

[wolfgangwalther]

The dbSettingsNames include db_tx_end but the docs configuration page says that db_tx_end is n/a for in-db config.

A good catch. I added it in aef29d4.

More the dbSettingsNames include raw_media_types but there is no detail available around this config in the documentation.

We removed raw-media-types in v12.0.0 and replaced it with aggregation / media handlers. Removed the left-over in c6f152f.

[wolfgangwalther]

Please rebase, solving conflicts with CHANGELOG.md.

[laurenceisla]

Since they're kinda breaking changes, these should go under a separate subtitle (after the ### Fixed entries like in the 10.1.0 changelog), something like:

### Changed
 - #3248, Modified some CLI options - @taimoorzaeem
   + Replace ``-e`` and ``--example`` with ``--example-file``
   + Rename option ``--dump-schema`` to ``--dump-schema-cache``

[steve-chavez]

Is it possible to make these options non-breaking changes?

[laurenceisla]

I initially proposed to not break the options in #3321 (review), but we agreed to only use the new ones at the end of that review... if we'd like to go back to not breaking the options, then we could use that implementation.

[laurenceisla]

These should be commented since they do not have a default value, and should also show a sample value (similar to how db-anon-role works). Only checked for the changes in the --example-file, maybe others are missing (verify in the docs: if they have "Default: n/a" then they should be commented).

[steve-chavez]

Hm, the newly added env vars and db options look hard to maintain.

I'm thinking we should somehow auto-generate them.

Also the in-db config format is not really future-proof as we're transitioning to a pre_config function: https://postgrest.org/en/v12/references/configuration.html#in-database-configuration

[laurenceisla]

Hm, the newly added env vars and db options look hard to maintain.

I'm thinking we should somehow auto-generate them.

That's a good idea, we could use a sample configuration and the function used to detect valid in-db configs. Although I believe that it would be a bit tricky to implement (perhaps in another PR?).

Also the in-db config format is not really future-proof as we're transitioning to a pre_config function: https://postgrest.org/en/v12/references/configuration.html#in-database-configuration

Hmm... then maybe printing a sample function instead of modifying a role would be the best here? or maybe both?