From cd6a249e3102cb6eeb58e3b33255451e046e0f37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Tue, 22 Oct 2024 17:43:53 +0200 Subject: [PATCH] docs: added release note --- releases/v1.0.0.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 releases/v1.0.0.md diff --git a/releases/v1.0.0.md b/releases/v1.0.0.md new file mode 100644 index 0000000..b476588 --- /dev/null +++ b/releases/v1.0.0.md @@ -0,0 +1,73 @@ +🎉 xk6-sql `v1.0.0` is here! + +## Modularization + +This release contains a major refactoring, the modularization of the previously monolithic `xk6-sql`. The database driver integrations have been extracted into separate k6 driver extensions. + +Although modularization means a small API modification, it is basically a **breaking change!** + +## How it Works + +The SQL database driver integration is implemented in a separate k6 extension. The JavaScript API of this extension contains a single default export whose type is [JavaScript Symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) and is used to specify the database driver in the [xk6-sql API](https://sql.x.k6.io). + +The use of the Symbol type is necessary in order to force the import of the driver module. + +```JavaScript +import sql from "k6/x/sql" +import sqlite3 from "k6/x/sql/sqlite3" + +const db = sql.open(sqlite3, "./test.db") +``` + +## Drivers + +For easier discovery, the `xk6-sql-driver` topic is included in the database driver extensions repository. The [xk6-sql-driver GitHub topic search](https://github.com/topics/xk6-sql-driver) therefore lists the available driver extensions. + +During the refactoring, the following k6 SQL database driver extensions were created from the database drivers previously embedded in the xk6-sql extension: + +- https://github.com/grafana/xk6-sql-driver-mysql +- https://github.com/grafana/xk6-sql-driver-postgres +- https://github.com/grafana/xk6-sql-driver-sqlite3 +- https://github.com/grafana/xk6-sql-driver-azuresql +- https://github.com/grafana/xk6-sql-driver-sqlserver +- https://github.com/grafana/xk6-sql-driver-clickhouse + +The following template repository can be used to create a new driver extension: https://github.com/grafana/xk6-sql-driver-ramsql + +## Solved problems + +1. New SQL database type support (integration of new golang database/sql driver) does not require changes to the source code of `xk6-sql` and the release of `xk6-sql`. + +2. Supporting additional database drivers does not increase the size of `k6`. Since the database drivers are implemented in a separate `k6` extension, it is sufficient to embed only the drivers you want to use. + +3. The SQL database driver integration created by the community can be maintained by the community. Since database drivers are implemented as `k6` extensions, the community can create and maintain driver modules independently of Grafana. + +4. Drivers may have different requirements. For example, cgo (`CGO_ENABLED`) should only be enabled if a driver needs it. (like `sqlite3`). + +5. From the security perspective, the attack surface is smaller if fewer dependencies are embedded. + +## Build + +The [xk6](https://github.com/grafana/xk6) build tool can be used to build a k6 that will include **xk6-sql** extension **and database drivers**. + +> [!IMPORTANT] +> In the command line bellow, **xk6-sql-driver-ramsql** is just an example, it should be replaced with the database driver extension you want to use. +> For example use `--with github.com/grafana/xk6-sql-driver-mysql` to access MySQL databases. + +```bash +xk6 build --with github.com/grafana/xk6-sql@latest --with github.com/grafana/xk6-sql-driver-ramsql@latest +``` + +## API Compatibility + +The `xk6-sql` JavaScript API changes in an incompatible way because of the driver parameter type becomes Symbol instead of String. + +## API documentation + +A TypeScript declaration file was created for the `xk6-sql` API, from which an [API documentation site](https://sql.x.k6.io) is generated. + +## MySQL TLS support + +MySQL TLS configuration support has been moved to the driver extension: https://github.com/grafana/xk6-sql-driver-mysql + +It is important to note that the MySQL TLS configuration API will change in the future.