Improve caveats handling for API installs

[nbro]

brew gist-logs <formula> link OR brew config AND brew doctor output

brew gist-logs postgresql@14 gives me the error

Error: Your Xcode (13.4.1) is outdated.
Please update to Xcode 14.2 (or delete it).
Xcode can be updated from the App Store.

I am on Monterey. I don't think I can update XCode.

---

Anyway, I can execute the other commands.

brew config produces

HOMEBREW_VERSION: 4.2.21
ORIGIN: https://github.com/Homebrew/brew
HEAD: 82c2e743a5bcea725f9ca1429e3e21c3088ff904
Last commit: 7 days ago
Core tap HEAD: 8d3d8f6d5b0934b62901f3abe31469db49082cb5
Core tap last commit: 45 minutes ago
Core tap JSON: 12 May 23:18 UTC
Core cask tap HEAD: 11e324365a89fcd2980dc78c973a594a380b7719
Core cask tap last commit: 2 hours ago
Core cask tap JSON: 12 May 23:18 UTC
HOMEBREW_PREFIX: /usr/local
HOMEBREW_CASK_OPTS: []
HOMEBREW_MAKE_JOBS: 8
Homebrew Ruby: 3.1.4 => /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/3.1.4/bin/ruby
CPU: octa-core 64-bit haswell
Clang: 13.1.6 build 1316
Git: 2.32.1 => /Applications/Xcode.app/Contents/Developer/usr/bin/git
Curl: 8.4.0 => /usr/bin/curl
macOS: 12.7.4-x86_64
CLT: 14.2.0.0.1.1668646533
Xcode: 13.4.1

brew doctor produces

Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: You have the following deprecated, cask taps tapped:
  caskroom/cask
Untap them with `brew untap`.

Warning: Some installed formulae are deprecated or disabled.
You should find replacements for the following formulae:
  openssl@1.1
  python@3.8

Warning: You have unlinked kegs in your Cellar.
Leaving kegs unlinked can lead to build-trouble and cause formulae that depend on
those kegs to fail to run properly once built. Run `brew link` on these:
  numpy
  kubernetes-cli
  gnupg

Warning: You have an unnecessary local Cask tap.
This can cause problems installing up-to-date casks.
Please remove it by running:
  brew untap homebrew/cask

Warning: You have an unnecessary local Core tap!
This can cause problems installing up-to-date formulae.
Please remove it by running:
 brew untap homebrew/core

Warning: Homebrew's "sbin" was not found in your PATH but you have installed
formulae that put executables in /usr/local/sbin.
Consider setting your PATH for example like so:
  echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc

Warning: Your Xcode (13.4.1) is outdated.
Please update to Xcode 14.2 (or delete it).
Xcode can be updated from the App Store.

Verification

• My brew doctor output says Your system is ready to brew. and am still able to reproduce my issue.
• I ran brew update and am still able to reproduce my issue.
• I have resolved all warnings from brew doctor and that did not fix my problem.
• I searched for recent similar issues at https://github.com/Homebrew/homebrew-core/issues?q=is%3Aissue and found no duplicates.

What were you trying to do (and why)?

Start PostgreSQL as a background service using brew services start postgresql@14

What happened (include all command output)?

If I do brew services list, I get

Name          Status User File
dbus          none        
httpd         none        
php           none        
postgresql@14 none        
symfony-cli   none        
unbound       none  

So, postgresql@14 is a service. Now, I want to start this service. So, I did brew services start postgresql@14, which produces the following output

==> Successfully started `postgresql@14` (label: homebrew.mxcl.postgresql@14)

Now, if I do brew services list again, I get

Name          Status     User File
dbus          none            
httpd         none            
php           none            
postgresql@14 error  512 me ~/Library/LaunchAgents/homebrew.mxcl.postgresql@14.plist
symfony-cli   none            
unbound       none   

If I open ~/Library/LaunchAgents/homebrew.mxcl.postgresql@14.plist, I see the logs are at /usr/local/var/log/postgresql@14.log.

Now, if I open /usr/local/var/log/postgresql@14.log, I get many errors like this

// Many other same errors here
//
postgres: could not access directory "/usr/local/var/postgresql@14": No such file or directory
Run initdb or pg_basebackup to initialize a PostgreSQL data directory.

Now, effectively, I don't have the folder /usr/local/var/postgresql@14, but I have the folder /usr/local/var/postgres.

Now, when I execute brew services start postgresql (so without the suffix @14), I get the warning Warning: Formula postgresql was renamed to postgresql@14., so maybe the rename is causing this issue, i.e. the formula was renamed but the data directory wasn't? Anyway, shouldn't brew services start postgresql@14 automatically create the folder /usr/local/var/postgresql@14 if it doesn't exist? If yes, is this a bug then? According to https://formulae.brew.sh/formula/postgresql@14

This formula has created a default database cluster with:
    initdb --locale=C -E UTF-8 $HOMEBREW_PREFIX/var/postgresql@14
For more details, read:
    https://www.postgresql.org/docs/14/app-initdb.html

Apparently, in my case, that didn't happen.

My problem is vaguely similar to https://apple.stackexchange.com/questions/451097/brew-postgresql14-error-on-mac-m2, but my error in the logs is quite different.

I've not tried to manually create /usr/local/var/postgresql@14 because, if this is a bug, it probably should be fixed and that folder should be automatically created.

I thought of uninstalling postgresql and remove all configuration files, but this may be too dangerous, although I don't think I have anything important in this machine. Anyway, I don't really know what commands I should really use to make a clean installation again. I've looked at https://stackoverflow.com/a/57326013/3924118, but it would be nice to have an authoritative answer

What did you expect to happen?

PostgreSQL starts, no error occurs, and I can access it

Step-by-step reproduction instructions (by running brew commands)

See above

[nbro]

I solved the problem by just uninstalling and installing again postgresql@14 and then manually running

initdb --locale=C -E UTF-8 /usr/local/var/postgresql@14

which should have been run automatically, according to the message we see when we install postgresql@14

...
This formula has created a default database cluster with:
  initdb --locale=C -E UTF-8 /usr/local/var/postgresql@14
For more details, read:
  https://www.postgresql.org/docs/14/app-initdb.html
...

So, there's a bug either in the installation or documentation/message

[carlocab]

The caveats¹ should've shown you how to handle this but this doesn't interact well with API installs. So that is a bug. CC @Homebrew/brew

Footnotes

1. https://github.com/Homebrew/homebrew-core/blob/262db065cc1ce35f13b143a145b7580e9447a00f/Formula/p/postgresql%4014.rb#L141-L168 ↩

[MikeMcQuaid]

Agreed on 🐛. Fix should be:

• print caveats unconditionally in this case
• add a RuboCop to avoid if/unless in caveats

[carlocab]

Agreed on 🐛. Fix should be:

• print caveats unconditionally in this case

• add a RuboCop to avoid if/unless in caveats

I can see how this might be our most viable fix, but I'd strongly prefer a solution that retains the if and unless calls here.

Many users blindly run what caveats show them, so I'd like to avoid showing them commands we know they don't need to run. Adding notes that most users can ignore to caveats will also tend to make them ignore ones they shouldn't.

[MikeMcQuaid]

I can see how this might be our most viable fix, but I'd strongly prefer a solution that retains the if and unless calls here.

I can't see how this can be made to work with the API unless we're embedding Ruby source.

[carlocab]

I can't see how this can be made to work with the API unless we're embedding Ruby source.

I'm not opposed to that, but I don't think we need to. There is already a mechanism for fetching the Ruby source separately, which is why we have the ruby_source_checksum in the API JSON. Alternatively, the Ruby source is in the bottle, so we can read that after pouring and update the caveats from there.

[MikeMcQuaid]

Alternatively, the Ruby source is in the bottle, so we can read that after pouring and update the caveats from there.

This would work. Would mean it's not going to show with brew info before installation, in case that matters.

[carlocab]

Would mean it's not going to show with brew info before installation, in case that matters.

This is fine with me, I think.