sqlCommenter
qb supports the sqlCommenter specification by Google for appending contextual information to executed queries.
sqlCommenter support is off by default, but can be activated by setting the sqlCommenter.enabled
setting.
Once enabled, qb will append a comment on to every non-commented query. This happens as the query is ran, so you will not see this output when calling toSQL()
or dump()
.
sqlCommenter will only add a comment to non-commented queries. If you query contains a comment anywhere in it, sqlCommenter will ignore it.
An example query with a sqlCommenter comment looks like this:
Configuring sqlCommenter
The default configuration structure for sqlCommenter is as follows:
When the enabled
flag is false
, no comments will be appended.
The commenters
array are the different components that will add contextual information to each query. You define them by defining a struct with a class
key pointing to a WireBox mapping and a properties
key containing a struct of any necessary properties.
Commenters
Each Commenter must implement the ICommenter
interface. (The implements
keyword is not required.). They will be called with the sql
being commented and the current datasource
. It should return a struct of key/value pairs that will become comments.
Here is an example of the FrameworkCommenter@qb
:
You may use any. all, or none of the commenters
provided by qb. You may also create your own for your application. You may even see commenters pop up on ForgeBox for popular use cases.
For example, if you use cbauth
(or cbsecurity
using cbauth
), this commenter will add the current user ID to each query.
Parsing Commented SQL
The comment generated by sqlCommenter is escaped and url-encoded. It can be reversed by calling the SQLCommenter.parseCommentedSQL
method with the full query or the SQLCommenter.parseCommentString
method with just the comment.
parseCommentedSQL
Parses a commented SQL string into the SQL and a struct of the key/value pair comments.
parseCommentString
Parses a comment string into a struct.
Integration with non-ColdBox applications
Out of the box, qb includes a ColdBoxSQLCommenter
. Since sqlCommenter adds contextual information, some level of framework or application integration is necessary. You can create your own sqlCommenter
instance by extending the qb.models.SQLCommenter.SQLCommenter
abstract component. If you create a SQLCommenter
for a specific framework, consider sharing it with others on ForgeBox.
Last updated