sqlite: remove statement.set* functions

[mike-git374]

Refs: #61235
Refs: #61262

[nodejs-github-bot]

Review requested:

• @nodejs/sqlite

[cjihrig]

These APIs have existed for a long time now and people are using them in the wild. It looks like #61311 only exists on v25. We shouldn't aggressively break users just because an API is still experimental. There isn't any harm in having both options - at least until the prepare() options exist on all supported branches.

It's also worth noting that chaining calls on the statement object seems to be more in line with how other SQLite libraries work. Neither better-sqlite3 nor bun:sqlite appear to have documented options passed to prepare(). This has the potential to cause problems for any libraries that try to create a uniform API on top of these different SQLite libraries.

[mike-git374]

Currently we are at Stability 1.2, breaking changes are part of the process, now would be a good time to do it. There are multiple more proposed options to add to db.prepare(), those would all need their own statement.set* functions, better to clean up the API now with a unified options interface.

---

Stability 1

Experimental. Non-backward compatible changes or removal may occur in any future release. Use of the feature is not recommended in production environments.

1.0 - Early development. Experimental features at this stage are unfinished and subject to substantial change.
1.1 - Active development. Experimental features at this stage are nearing minimum viability.
1.2 - Release candidate. Experimental features at this stage are hopefully ready to become stable. No further breaking changes are anticipated but may still occur in response to user feedback or the features' underlying specification development. We encourage user testing and feedback so that we can know that this feature is ready to be marked as stable.

Experimental features leave the experimental status typically either by graduating to stable, or are removed without a deprecation cycle.

---

Stability 2

Stable. Compatibility with the npm ecosystem is a high priority.

[cjihrig]

breaking changes are part of the process

They don't need to be. Just because you can do something doesn't mean that you should. That policy is more of a safeguard in case things really need to change in order to make progress. That is most definitely not the case here. We also want users to use this. They are less likely to do that if things are constantly breaking underneath them.

There are multiple more proposed options to add to db.prepare(), those would all need thier own statement.set* functions, better to clean up the API now with a unified options interface.

No, they don't need to.

These functions are in active use, and are very low maintenance cost. Please do not prioritize API purity over user pain. What you are proposing breaks existing code without a good way to do things across versions. For example, setReadBigInts() has been available since v22.5.0, while the prepare() option has only been available since v25.5.0. This puts library authors in a difficult situation if they need to read large numbers from their databases across Node versions.

Your comment also doesn't address the second part of #61920 (review). From a quick search, passing these options to prepare() seems to be more out of the ordinary.

[mike-git374]

There is a very clearly stated policy about breaking changes for experimental features. You agree db.prepare(SQL, options) is the better API:

I agree that using the options on prepare() is generally a better option.

It's important to set the API correctly during this time. I'd rather not deal with code that has multiple different ways to set the same options, it's confusing for users which method they are supposed to use, AI will require more tokens to read and understand the docs, more neurons required to compare the different methods. Let's have a single unified easy to understand options API, future options are easy to add and fit into the existing interface.

For example there is open PR here #61472 someone wants to add an option, they have added this to both old method statement.set* and new method db.prepare(sql, options). This is not good, better to have a single place for options.

More opinions are welcome to the conversation.

[cjihrig]

Let's have a single unified easy to understand options API

A single unified API that doesn't work across versions. Two working APIs is a better option. Sorry, but I'm not going to lift my block here. In the long term, I don't care what the API surface looks like, but IMO this is changing too much all at once. We've seen this play out before with experimental APIs being broken just because they can be. Users were angry.

[mike-git374]

Two working APIs is a better option

So you think every time there is a new option it needs to be added in 2 different places, like this PR #61472 ?

Sorry, but I'm not going to lift my block here

I believe Node.js is run by more than a single person, people who understand breaking changes policy for experimental features allows for breaking changes. I'm waiting for more opinions to come in, I understand you don't like it. So far we have 2 for the change with @mceachen #61262 (comment) and only 1 opposed (you).