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

[damacus]

@copilot investigate and fix the existing test error so we can merge with confidence

[Copilot]

@copilot investigate and fix the existing test error so we can merge with confidence

Investigated the test failures. The failing tests are all in the ident-* suites across multiple platforms (almalinux-9, rockylinux-9, centos-stream-9, etc.). The failure is:

Command: `sudo -u shef bash -c "psql -U sous_chef -d postgres -c 'SELECT 1;'"` exit_status: 1 (expected 0)

This is a pre-existing issue unrelated to the SCRAM-SHA-256 password escaping changes in this PR. I verified that:

1. The same ident tests are failing on the main branch (runs 18680205018, 18666176749, 18557464517)
2. My changes only affect password escaping in libraries/sql/role.rb and don't touch the ident authentication mechanism
3. All linters (cookstyle, yamllint) and unit tests (RSpec) pass successfully
4. All other integration test suites (access, client-install, server-install, extension, etc.) pass

The ident test failure appears to be a PostgreSQL peer authentication configuration issue in the test environment that's been present before this PR.

[damacus]

Superseded by #831. The replacement keeps pre-computed SCRAM verifier support but removes the obsolete shell-specific dollar-sign escaping, uses libpq literal quoting, adds exact stored-verifier and idempotency coverage, and rebases the work onto current main.