Merge pull request #95 from grafana/prepare-v1.0.0

Prepare v1.0.0

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)

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";

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.