From 3a9553fc03b372003005b075d1bcfe82d11291f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Tue, 22 Oct 2024 17:43:41 +0200 Subject: [PATCH 1/3] docs: fix latest release link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b778b5d..36018e9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ [![API Reference](https://img.shields.io/badge/API-reference-blue?logo=readme&logoColor=lightgray)](https://sql.x.k6.io) -[![GitHub Release](https://img.shields.io/github/v/release/grafana/xk6-sql)](https://github.com/grafana/xk6-sql/releases/) +[![GitHub Release](https://img.shields.io/github/v/release/grafana/xk6-sql)](https://github.com/grafana/xk6-sql/releases/latest) [![Go Report Card](https://goreportcard.com/badge/github.com/grafana/xk6-sql)](https://goreportcard.com/report/github.com/grafana/xk6-sql) [![GitHub Actions](https://github.com/grafana/xk6-sql/actions/workflows/test.yml/badge.svg)](https://github.com/grafana/xk6-sql/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/grafana/xk6-sql/graph/badge.svg?token=DSkK7glKPq)](https://codecov.io/gh/grafana/xk6-sql) 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 2/3] 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. From c8414f90acde043a5ce9da76cd61d8ae18c1c9f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Tue, 22 Oct 2024 17:44:10 +0200 Subject: [PATCH 3/3] docs: added intro section --- index.d.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/index.d.ts b/index.d.ts index f78c69b..12286f3 100644 --- a/index.d.ts +++ b/index.d.ts @@ -4,6 +4,14 @@ * xk6-sql is a [Grafana k6 extension](https://grafana.com/docs/k6/latest/extensions/) that enables * the use of SQL databases in [k6](https://grafana.com/docs/k6/latest/) tests. * + * In order to use the `xk6-sql` API, in addition to the `k6/x/sql` module, + * it is also necessary to import at least one driver module. + * The default export of the driver module is a driver identifier symbol, + * which should be passed as a parameter of the `open()` function. + * + * The driver module is typically available at `k6/x/sql/driver/FOO`, + * where `FOO` is the name of the driver. + * * @example * ```ts file=examples/example.js * import sql from "k6/x/sql";