feat: Add support for header comments in ORM-generated queries

[wwoytenko]

Hi Everyone!

A common challenge when using ORMs is the difficulty of correlating an executed query in the DBMS with the lines of code that triggered it. To solve this issue, it would be helpful to add a comment in the header of the generated query. In this implementation, if a context with a comment is provided, we’ll include that as a comment in the query.

Since I couldn’t find an existing feature to add header comments to queries, I’ve built this functionality myself.

Here’s an example of how to use it:

type testTable struct {
	tableName struct{} `pg:"test"`
	ID        int64    `pg:"id"`
	Title     string   `pg:"title"`
}
m := testTable{}
ctx = pg.SetQueryComment(context.Background(), "test_query_name")
_, err := db.ModelContext(ctx, &m).Insert()

This will generate an INSERT statement with the following comment:

/* test_query_name */ INSERT INTO ...

I’ve added two public functions: SetQueryComment and GetQueryComment. On the one hand, we could keep only SetQueryComment (and potentially remove GetQueryComment), but on the other hand, GetQueryComment may be useful for integration with other wrappers and services that require access to the query comment from context

[wwoytenko]

I reverted the changes in db_test that were made by mistake. Should I squash the commits?

[elliotcourant]

I think this is a reasonable thing to add, but I don't think it should be via the context provider as that makes things a bit odd.

Let's say I want to pass something like both the trace ID and the current user's account ID in, I would have to create a new context just for that and add the value; with at least one of those values already being on the context in another shape (the trace ID via otel at least). And as I understand it; unwrapping the context is not expensive, but its not cheap either?

What would you think of just adding a function to the query struct that would do what youre already doing, but would allow an arbitrary string to be passed to it and maybe escaped?

That way the way the comment gets onto the query is relatively implementation agnostic, someone could still pass data via context down and simply plop it in via before query. Or someone could add it only for specific queries?

[elliotcourant]

I reverted the changes in db_test that were made by mistake. Should I squash the commits?

I wouldn't worry about squashing commits, github can take care of that

[wwoytenko]

And as I understand it; unwrapping the context is not expensive, but its not cheap either?

Sure

What would you think of just adding a function to the query struct

I will check how I could implement it in the Query struct. I will keep you updated

[wwoytenko]

Hi @elliotcourant,
I believe you're able to review the changes now.
I tried to find an easier way for Query to write a comment directly into the provided buffer, but I was only able to modify the AppendQuery method in all public structures that implement QueryAppender. I’d love to hear your opinion on this approach. Thanks in advance!

[wwoytenko]

Now it works this way

type testTable struct {
	tableName struct{} `pg:"test"`
	ID        int64    `pg:"id"`
	Title     string   `pg:"title"`
}
m := testTable{}
_, err := db.ModelContext(ctx, &m).Comment("test").Insert()

[elliotcourant]

This looks great to me so far, Would you be able to add some tests to make sure that its escaping things properly and then I think this should be fine to merge.

[wwoytenko]

Thank you @elliotcourant!
I've just added some tests for appendComment func