Updated db defined type strings documentation (#1)

[benjamin-robertson]

Updates to Puppet strings documentation for mysql module.

Regenerated Reference.md

Fixes issue #1455

[CLAassistant]

All committers have signed the CLA.

[puppet-community-rangefinder]

mysql::db is a type

Breaking changes to this file WILL impact these 67 modules (exact match):

• mmitchell-puppetlabs_ironic
• puppetlabs-bacula
• infnpd-ocpattrauth
• lboynton-gitlab
• cnwr-cacti
• forj-openfire
• fiddyspence-zabbix
• binford2k-drupal
• wyrie-snmptt
• alkivi-owncloud
• mricon-bugzilla
• alkivi-zabbix
• eelcomaljaars-friendica
• monkygames-beansbooks
• qroac-isp3node
• martialblog-limesurvey
• samuelson-custom_webapp
• akisakye-matomo
• tscopp-jss
• hgkamath-owncloud
• brucem-ezpublish
• stesie-gluon
• martasd-mediawiki
• alisio-opensipscp
• othalla-nextcloud
• bramwelt-patchwork
• hexmode-mediawiki
• sgnl05-racktables
• ccaum-autoami
• shoekstra-owncloud
• rharrison-bacula
• alisio-opensips
• desalvo-bacula
• benjaminrobertson-observium
• leonardothibes-usvn
• wyrie-nagiosql
• dsestero-sonarqube
• firefield-firefield
• bodgit-wordpress
• cirrax-roundcube
• dmcnicks-sympa
• mightp-librenms
• marcdeop-ratticdb
• aimonb-nexusis_gerrit
• icann-opendnssec
• cirrax-postfixadmin
• jefferyb-kualicoeus
• ULHPC-slurm
• treydock-slurm
• aimonb-nexusis_mediawiki
• autostructure-artifactory
• sensson-powerdns
• oris-appserver
• fervid-artifactory
• razorsedge-cloudera
• maxadamo-galera_proxysql
• cesnet-site_hadoop
• treydock-xdmod
• openstack-monasca
• puppet-zabbix
• factorit-jasperreports_server
• SchnWalter-happydev
• jsnshrmn-twlight
• geoffwilliams-r_profile
• blackknight36-bacula
• treydock-keycloak
• wdijkerman-zabbix

Breaking changes to this file MAY impact these 16 modules (near match):

• mwils-complete_wordpress
• kclnmssys-sympa
• abaranov-sqlgrey
• erwbgy-wso2
• devopera-domysqldb
• cesnet-oozie
• jtopjian-cubbystack
• tykeal-gerrit
• echoes-wrappers
• cesnet-hive
• soli-wrappers
• lcgdm-lcgdm
• lcgdm-dmlite
• halyard-boxen
• rspiak-racktables
• icinga-icinga

This module is declared in 140 of 579 indexed public Puppetfiles.

---

These results were generated with Rangefinder, a tool that helps predict the downstream impact of breaking changes to elements used in Puppet modules. You can run this on the command line to get a full report.

Exact matches are those that we can positively identify via namespace and the declaring modules' metadata. Non-namespaced items, such as Puppet 3.x functions, will always be reported as near matches only.

[chelnak]

Hey! Thanks for your contribution. Would you be able to provide a little more context around your proposed change?

Thanks 😊

[benjamin-robertson]

Hi Craig,

It appears that both the charset and collate parameters both need to be set. If only charset is set we continually receive corrective changes on Puppet runs.

For example if you configure the following

  mysql::db { 'bensdb':
    user     => ben,
    password => lookup('mysql::server::root_password'),
    host     => 'localhost',
    grant    => 'ALL',
    charset  => 'latin1',
  }

Corrective changes will continually occur for collate.

See notes from below issue ticket.

Thanks

Ben

Currently, charset and collate parameters for the defined type mysql::db don't mention in the docs they need to both set to the same charset. EG

  mysql::db { 'bensdb':
    user     => ben,
    password => lookup('mysql::server::root_password'),
    host     => 'localhost',
    grant    => 'ALL',
    charset  => 'latin1',
    collate  => 'latin1_swedish_ci',
  }

If they are not both set; corrective changes continually occur.

Notice: /Stage[main]/Profile::Lab::Mysql/Mysql::Db[bensdb]/Mysql_database[bensdb]/collate: collate changed 'latin1_swedish_ci' to 'utf8_general_ci' (corrective)
Next run
Notice: /Stage[main]/Profile::Lab::Mysql/Mysql::Db[bensdb]/Mysql_database[bensdb]/charset: charset changed 'utf8mb3' to 'latin1' (corrective)
Next run
Notice: /Stage[main]/Profile::Lab::Mysql/Mysql::Db[bensdb]/Mysql_database[bensdb]/collate: collate changed 'latin1_swedish_ci' to 'utf8_general_ci' (corrective)

I propose changing the parameter descriptions from

# @param charset
#   The character set for the database.
# @param collate
#   The collation for the database.

To

# @param charset
#   The character set for the database. Must be set with collate to avoid corrective changes.
# @param collate
#   The collation for the database. Must be set with charset to avoid corrective changes.

[chelnak]

Hey Ben, thanks for such a detailed response.

I think what you are suggesting makes sense and I also think that we could probably do some more in that area to make the defined type a bit more robust.

That would take some time right now so I think a docs update is a good interim solution.

How about we make the descriptions read something like:

"Must have the same value as X to avoid corrective changes"

I think that makes the intention a little more explicit.

What do you think?

[benjamin-robertson]

Hi Craig,

Updated as suggested; I also provided a link to the mysql page which explains how to view the charset and collate pairs. Since the names don't match exactly.

Thoughts?

Ben

[chelnak]

This is great.

There is a double space at the start of "Must" on line 23. If you could fix that so it matches the previous description then we can get this merged!

[chelnak]

Just one small change then we are looking good!

[benjamin-robertson]

Space fixed. Sneaky space.