Enhance spring.datasource.initialization-mode property description

[nikmanzotti]

As discussed here #20920 and here #21077 with @snicoll, we think that the description may of the spring.datasource.initialization-mode could be improved.

I understand that the description is generated from the code comment, which states:

Initialize the datasource with available DDL and DML scripts.

In the current docs dedicated section, the description field is empty (I've opened another issue for this specific problem, see #21131).

I have reviewed my initial enhancement proposal after viewing the original description and receiving some feedback.

I've done some research, in the Spring Framework documentation they use "DataSource implementations" and "Database types" to refer to the actual DBMS (e.g. H2, Derby, HSQL - see 3.2. Package Hierarchy, 3.9. Embedded Database Support). I suppose it's a wording valid for both embedded and "non-embedded" databases, so not suitable for the values of the spring.datasource.initialization-mode property.

Updated proposal:

Initialize the embedded datasource with available DDL and DML scripts. Use always to initialize any datasource.

This avoids the use of "type of datasource", and describes the usage of always as a value, but I'm still not sure if is it clearly understandable.

Also, I was guessing: is there a way to disable datasource initialization, even if the DDL and DML scripts are present?

[snicoll]

Initialize the embedded datasource with available DDL and DML scripts. Use always to initialize any datasource.

Thanks for the suggestion. I don't like this proposal as it is documented towards its default value.

Also, I was guessing: is there a way to disable datasource initialization, even if the DDL and DML scripts are present?

This question probably explains why you are raising this issue in the first place. The three values for that property are documented. never can be used to not initialize the database.

I think rather than being imperative about the fact the datasource is going to be initialized, we should update the description to focus that this controls the "mode" of initialization.

[nikmanzotti]

Thanks for the feedback! You are right, I am quite new to Spring Boot (to the whole programming world, actually) and I have still many things to understand and learn.

Being the description related only to the default value, I agree with you. This is an updated proposal, but I am still not sure it makes things clear enough:

If the datasource is an embedded one, initialize it with available DDL and DML scripts.

---

P.S. do you think it would be worth adding a Note block (or something else) to explain where the complete documentation of the properties and their values could be found? It would be aimed mostly at beginners, and I am not sure it is something easy to generalize. For instance, I can see comments for LiquibaseProperties attributes looking at the Java code, but I wasn't able to find them in the class Javadoc.

[snicoll]

Being the description related only to the default value, I agree with you. This is an updated proposal, but I am still not sure it makes things clear enough:

If the datasource is an embedded one, initialize it with available DDL and DML scripts.

Thanks for the feedback but that's still a description towards its default value. If you set the value of this property to always or never the description reads completely wrong to me.

P.S. do you think it would be worth adding a Note block

Let's not start two different topics in one issue please as it makes it very hard to understand what is going on. Feel free to join the community on Gitter if you want to chat about an idea or create a separate issue.

Having said that, descriptions are available in your IDE and in the appendix of the reference guide. I would argue that ConfigurationProperties is not what you should look at to learn about a feature as it is a relatively low-level part and internal to the framework. Discovering properties by typing liquibase in your IDE or searching in the reference documentation is what I would expect a beginner to do.