Introducing a standard interface for database drivers

[halvardssm]

In the JS ecosystem for database drivers, this package is one of the more widely used. Together with the Deno Standard Library team, we have been working on creating a standard interface for JS that database drivers can adopt to provide consistency in how to interact with sql based databases, similar to what exists for the Go ecosystem.

In the JS community, we are quite wary of any breaking changes, or alterations of existing signatures, which is why this would not require a rewrite of existing code, but can live alongside the existing implementations. If the interface is adopted into the project, it is possible and also encouraged to provide both the existing exports alongside the new exports to allow for gradual adoption.

I am opening this issue to introduce the project, and to hopefully spark interest from the maintainer team to engage, contribute and potentially adopt the interfaces into this package. The current implementation of the standard interface is more or less stable, but if any overlooked issues or concerns surface, the implementation is open for amendments. I am also happy to provide implementation support if it helps adoption.

If this project is of interest to you, feel free to read the full specifications in the RFC PR, and comment here or in the RFC. And feel free to reach out if a further discussion is wanted.

Issues has been created for other popular db driver packages, and existing implementations can be found for the following drivers:

• Deno SQLite: Implemented stdext/sql interfaces denodrivers/sqlite3#135
• Deno MySQL: Implement SQLx interface denodrivers/mysql#170

[wellwelwel]

Hi, @halvardssm. It's really great.

Together with the Deno Standard Library team, we have been working on creating a standard interface for JS that database drivers can adopt to provide consistency in how to interact with sql based databases, similar to what exists for the Go ecosystem.

When you say ecosystem, could you explain how this would also be reflected in Node.js and Bun (especially on interoperability)?

For example, in #2711 and #2714 we refactored some things to allow interoperability with Deno, which was a challenge since MySQL2 is a CommonJS project (the proposal is to ensure full compatibility with Node.js, Bun, and Deno and a useful way to do this was be able to run the same test suite for all platforms).

I believe that understanding how this migration would affect other environments would be of great value to all the projects that you have also recommended interfacing with 🤝

[halvardssm]

Hi @wellwelwel , and thank you for raising the questions and concerns!

To clarify, these interfaces are runtime agnostic, meaning that as long as it is JS, it does not matter. The interfaces are being introduced to create a standard way of connecting and querying across runtimes and drivers. And it is up to the respective drivers to decide which runtimes they want to support.

The fact that this is a CommonJS project does not create any immediate issues. The interfaces are well documented, and can be implemented without having to write the codebase in typescript. Of course, it will reduce some lines of code for you if the types make use of the interfaces from the module, but it is not required to be compatible.

The goal for introducing a standard interface is to improve the development experience, so that the users of the drivers can easily transition from one driver to another (pg, sqlite, mysql etc.). In the end it's all about making the ecosystem easier to traverse.

Did I cover your concerns?

[sidorares]

I fully support common interface, but not sure if changing mysql2 to it is possible/practical in a backwards compatible way

some possible options:

• if the methods do not overlap ( or overlap but different signatures do not cause confusion ) we can just add them to the connection/pool objects
• if there is a big difference in current mysql2 and "standard" interface maybe it's better to create a module that wraps mysql2 ( or mysqljs/mysql ) driver and exposes it under the new api

I'd personally prefer to split current codebase into "just the protocol" part - framing, core types deserialisation, packets serialisation/deserialisation, commands state machine and "nice api" part - streamed/non streamed responses, expressing prepared parameters and types, different conventions on how to store results and result types etc

[halvardssm]

Hey @sidorares ! And exciting to hear that you are supportive of the standard interface!

I see your points, so let me just clarify that you don't need to change the existing API, as the current API and the standard interface can live alongside each other without too much adjustment (see how the new interface is wrapped around the existing API for sqlite here). Because of this, I would say that your option 2 would be the better road in the beginning.

So the interfaces can also be split into two parts, the base "protocol" as you mentioned is essentially the connection interface, the rest would be the higher level "nice" api.

Let me know if there is anything else I can clarify!