fix(role): Add automatic SCRAM-SHA-256 password escaping and docs

[Copilot]

• Add automatic SCRAM-SHA-256 password escaping and comprehensive documentation
• Address code scanning alerts for incomplete string escaping
• Use nil_or_empty? function for password validation check as suggested in code review
• Fix backslash escaping in SCRAM-SHA-256 password handling
• Fix markdownlint issues in SCRAM-SHA-256 documentation

Changes

This PR addresses the SCRAM-SHA-256 password handling issue where $ characters in password hashes were being mangled during SQL execution, causing authentication failures.

Key improvements:

• Automatic Detection: The cookbook detects passwords starting with SCRAM-SHA-256
• Transparent Escaping: $ characters are automatically escaped as \$ to prevent shell interpretation
• Proper Backslash Escaping: Fixed excessive backslash escaping from \\\\\\\\ to proper \\\\ for SQL safety
• Backward Compatible: Only affects SCRAM-SHA-256 passwords; all other formats remain unchanged
• Code Quality: Used existing nil_or_empty? utility function for cleaner password validation
• Documentation Quality: Fixed all markdownlint issues for proper documentation formatting

Solution

Users can now simply write:

postgresql_role 'user1' do
  encrypted_password 'SCRAM-SHA-256$4096:salt$key:server'
  action [:create, :update]
end

The cookbook automatically escapes the password for safe SQL execution.

Testing

Verified that:

• SCRAM-SHA-256 passwords are properly escaped (both $ and \ characters)
• All existing password formats (MD5, plain text, etc.) remain unchanged
• Integration test successfully creates users with SCRAM-SHA-256 passwords
• Backslash escaping uses proper SQL escaping (not excessive escaping)
• Documentation passes all markdownlint checks

Fixes #703.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[damacus]

This is ready to release. But I'm going to move it over to the new release workflow before releasing.

[github-actions]

Slowest examples

Top 10 slowest examples (0.02 seconds, 53.28% of total time)

Example	Description	Time in seconds
spec/libraries/helpers_spec.rb:19	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 11 from repo returns the correct path	0.01336
spec/libraries/role_spec.rb:70	PostgreSQL::Cookbook::SqlHelpers::Role #escape_password_for_sql with edge cases handles nil passwords	0.00286
spec/libraries/helpers_spec.rb:27	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 11 from os returns the correct path	0.00097
spec/libraries/helpers_spec.rb:35	PostgreSQL::Cookbook::Helpers#data_dir(version) with debian family and Postgres 11 from repo returns the correct path	0.00066
spec/libraries/helpers_spec.rb:43	PostgreSQL::Cookbook::Helpers#data_dir(version) with debian family and Postgres 11 from os returns the correct path	0.00055
spec/libraries/helpers_spec.rb:73	PostgreSQL::Cookbook::Helpers#conf_dir(version) with debian family and Postgres 11 from repo returns the correct path	0.00047
spec/libraries/helpers_spec.rb:57	PostgreSQL::Cookbook::Helpers#conf_dir(version) with rhel family and Postgres 11 from repo returns the correct path	0.00047
spec/libraries/helpers_spec.rb:65	PostgreSQL::Cookbook::Helpers#conf_dir(version) with rhel family and Postgres 11 from os returns the correct path	0.00041
spec/libraries/helpers_spec.rb:119	PostgreSQL::Cookbook::Helpers#default_platform_service_name(version) with debian family and Postgres 11 from os returns the correct service name	0.0004
spec/libraries/helpers_spec.rb:95	PostgreSQL::Cookbook::Helpers#default_platform_service_name(version) with rhel family and Postgres 15 from repo returns the correct service name	0.00039

[github-actions]

Slowest examples

Top 10 slowest examples (0.01 seconds, 49.31% of total time)

Example	Description	Time in seconds
spec/libraries/helpers_spec.rb:19	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 11 from repo returns the correct path	0.0124
spec/libraries/role_spec.rb:70	PostgreSQL::Cookbook::SqlHelpers::Role #escape_password_for_sql with edge cases handles nil passwords	0.00302
spec/libraries/helpers_spec.rb:27	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 15 from os returns the correct path	0.00046
spec/libraries/helpers_spec.rb:111	PostgreSQL::Cookbook::Helpers#default_platform_service_name(version) with debian family and Postgres 11 from repo returns the correct service name	0.00039
spec/libraries/helpers_spec.rb:119	PostgreSQL::Cookbook::Helpers#default_platform_service_name(version) with debian family and Postgres 12 from os returns the correct service name	0.00038
spec/libraries/helpers_spec.rb:19	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 15 from repo returns the correct path	0.00038
spec/libraries/helpers_spec.rb:57	PostgreSQL::Cookbook::Helpers#conf_dir(version) with rhel family and Postgres 13 from repo returns the correct path	0.00038
spec/libraries/helpers_spec.rb:27	PostgreSQL::Cookbook::Helpers#data_dir(version) with rhel family and Postgres 11 from os returns the correct path	0.00037
spec/libraries/helpers_spec.rb:103	PostgreSQL::Cookbook::Helpers#default_platform_service_name(version) with rhel family and Postgres 14 from os returns the correct service name	0.00037
spec/libraries/helpers_spec.rb:35	PostgreSQL::Cookbook::Helpers#data_dir(version) with debian family and Postgres 13 from repo returns the correct path	0.00037