api improve suggestion

[wongoo]

Actual API

spo := orchestra2{Cello: "Strad", Bass: "Cecilio"}
query := sx.InsertQuery("symphony", &spo)  // INSERT INTO symphony (cello,contrabass) VALUES (?,?)
tx.MustExec(query, sx.Values(&spo)...)

Expected API

spo := orchestra2{Cello: "Strad", Bass: "Cecilio"}
tx.MustInsert("symphony", &spo)

And the same for update api.

[ders]

Thank you for the suggestion. This is indeed a cleaner API, but it also assumes that you want to regenerate the query for every row inserted, which is often not the case.

As an example, let's suppose we want to read orchestra2 objects from a channel and insert them. The code might look like this:

cacophony := make(chan orchestra2)

...

query := sx.InsertQuery("symphony", &orchestra2{})
tx.MustPrepare(query).Do(func(stmt *sx.Stmt) {
    for o := range cacophony {
        stmt.MustExec(query, sx.Values(&o)...)
    }
})

One could write similar code to insert objects from a slice, from a map, etc., but each use case would be slightly different.

If you find yourself using a particular pattern a lot, then it may be worth writing a helper function, e.g.

func quickInsert(tx *sx.Tx, table string, data interface{}) {
    tx.MustExec(sx.InsertQuery(table, data), sx.Values(data)...)
}

So the question we need to ask is: How useful would this particular helper function be, and should we add it as a method on tx? We'd like to be cautious about cluttering up the API with too many helpers.

[wongoo]

@ders so do u suggestion to create the query only once and use it repeatedly? if so, your example may need change to use a global variable, or add some comment to notice. if the query may be created every time when needed , the helper function api could be very useful.

[ders]

It's completely up to you whether you want to create the query once and reuse it, or create the query in each function or method that needs it. (It's just a string, after all!)

The point about MustInsert is this: There are a lot of shortcuts that we could add to make certain usage patterns easier. Choosing which shortcuts to include and which to leave out is often difficult. Our feeling at this point is that MustInsert is not something we need in the library: it wouldn't get used that often, and it's a one-liner to reproduce.

[wongoo]

get it, keep it simple, tks~