From 8830a27ad50e97803933e40fcc3e26291e52f0e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 11:41:06 +0200 Subject: [PATCH 01/10] docs: update docs --- CONTRIBUTING.md | 17 +++- Makefile | 19 ++++- README.md | 197 ++++++++++++++----------------------------- examples/example.txt | 24 ++++++ 4 files changed, 116 insertions(+), 141 deletions(-) create mode 100644 examples/example.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 804b957..c3b71a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# How to contribute to xk6-sql +# Contributing Guidelines Thank you for your interest in contributing to **xk6-sql**! @@ -70,17 +70,22 @@ go tool cover -html=coverage.out ### build - Build a custom k6 with the extension ```bash -CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql=. +CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql ``` [build]: <#build---build-a-custom-k6-with-the-extension> +### example - Run example + +```bash +./k6 run examples/example.js > examples/example.txt 2>&1 +``` + ### clean - Delete the build directory ```bash rm -rf build rm -f ./k6 -rm -f ./intg_test.db ``` ### format - Applies Go formatting to code @@ -99,3 +104,9 @@ Requires ```bash cdo --makefile Makefile ``` + +### readme - Update README.md + +```bash +mdcode update +``` diff --git a/Makefile b/Makefile index e5278c4..f807f20 100644 --- a/Makefile +++ b/Makefile @@ -12,9 +12,11 @@ __help__: @echo ' build Build a custom k6 with the extension' @echo ' clean Delete the build directory' @echo ' coverage View the test coverage report' + @echo ' example Run example' @echo ' format Applies Go formatting to code' @echo ' lint Run the linter' @echo ' makefile Generate Makefile' + @echo ' readme Update README.md' @echo ' test Run the tests' @echo ' tools Install the required tools' @@ -26,7 +28,7 @@ all: clean format test build .PHONY: build build: @(\ - CGO_ENABLED=1 xk6 build --with $$(go list -m)=.;\ + CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql;\ ) # Delete the build directory @@ -35,7 +37,6 @@ clean: @(\ rm -rf build;\ rm -f ./k6;\ - rm -f ./intg_test.db;\ ) # View the test coverage report @@ -45,6 +46,13 @@ coverage: test go tool cover -html=coverage.out;\ ) +# Run example +.PHONY: example +example: + @(\ + ./k6 run examples/example.js > examples/example.txt 2>&1;\ + ) + # Applies Go formatting to code .PHONY: format format: @@ -66,6 +74,13 @@ makefile: cdo --makefile Makefile;\ ) +# Update README.md +.PHONY: readme +readme: + @(\ + mdcode update;\ + ) + # Run the tests .PHONY: test test: diff --git a/README.md b/README.md index cea9f70..366432d 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,31 @@ # xk6-sql -This is a [k6](https://github.com/grafana/k6) extension using the -[xk6](https://github.com/grafana/xk6) system. +**Use SQL databases from k6 tests.** -Supported RDBMSs: `mysql`, `postgres`, `sqlite3`, `sqlserver`, `azuresql`, `clickhouse`. See the [examples](examples) -directory for usage. Other RDBMSs are not supported, see -[details below](#support-for-other-rdbmss). +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. -## Table of Contents -- [Build](#build) -- [Development](#development) -- [Example](#example) - - [TLS support](#tls-support) - - [Support for other RDBMSs](#support-for-other-rdbmss) -- [Docker](#docker) +## Usage -## Build - -To build a `k6` binary with this plugin, first ensure you have the prerequisites: - -- [Go toolchain](https://go101.org/article/go-toolchain.html) -- If you're using SQLite, a build toolchain for your system that includes `gcc` or - another C compiler. On Debian and derivatives install the `build-essential` - package. On Windows you can use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/). - Make sure that `gcc` is in your `PATH`. -- Git - -Then: - -1. Install `xk6`: - ```shell - go install go.k6.io/xk6/cmd/xk6@latest - ``` +To use the xk6-sql API, the `k6/x/sql` module and the driver module corresponding to the database type should be imported. In the example below, `k6/x/sql/driver/ramsql` is the RamSQL database driver module. -2. Build the binary: - ```shell - xk6 build --with github.com/grafana/xk6-sql - ``` +The driver module exports a driver ID. This driver identifier should be used to identify the database driver to be used in the API functions. - If you're using SQLite, ensure you have a C compiler installed (see the - prerequisites note) and set `CGO_ENABLED=1` in the environment: - ```shell - CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql - ``` - - On Windows this is done slightly differently: - ```shell - set CGO_ENABLED=1 - xk6 build --with github.com/grafana/xk6-sql - ``` - -## Development -To make development a little smoother, use the `Makefile` in the root folder. The default target will format your code, run tests, and create a `k6` binary with your local code rather than from GitHub. - -```bash -make -``` -Once built, you can run your newly extended `k6` using: -```shell - ./k6 run examples/sqlite3_test.js - ``` +**example** -## Example +```javascript file=examples/example.js +import sql from "k6/x/sql"; -```javascript -// script.js -import sql from 'k6/x/sql'; +// ramsql is hypothetical, the actual driver name should be used instead. +import driver from "k6/x/sql/driver/ramsql"; -const db = sql.open("sqlite3", "./test.db"); +const db = sql.open(driver, "test_db"); export function setup() { - db.exec(`CREATE TABLE IF NOT EXISTS keyvalues ( - id integer PRIMARY KEY AUTOINCREMENT, - key varchar NOT NULL, - value varchar);`); + db.exec(`CREATE TABLE IF NOT EXISTS namevalue ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name VARCHAR NOT NULL, + value VARCHAR + );`); } export function teardown() { @@ -81,104 +33,77 @@ export function teardown() { } export default function () { - db.exec("INSERT INTO keyvalues (key, value) VALUES('plugin-name', 'k6-plugin-sql');"); + db.exec("INSERT INTO namevalue (name, value) VALUES('extension-name', 'xk6-foo');"); - let results = sql.query(db, "SELECT * FROM keyvalues;"); + let results = sql.query(db, "SELECT * FROM namevalue WHERE name = $1;", "extension-name"); for (const row of results) { - console.log(`key: ${row.key}, value: ${row.value}`); + console.log(`name: ${row.name}, value: ${row.value}`); } } ``` -Result output: +
+output -```shell -$ ./k6 run script.js +```bash file=examples/example.txt - /\ |‾‾| /‾‾/ /‾‾/ - /\ / \ | |/ / / / - / \/ \ | ( / ‾‾\ - / \ | |\ \ | (‾) | - / __________ \ |__| \__\ \_____/ .io + /\ Grafana /‾‾/ + /\ / \ |\ __ / / + / \/ \ | |/ / / ‾‾\ + / \ | ( | (‾) | + / __________ \ |_|\_\ \_____/ - execution: local - script: /tmp/script.js - output: - + execution: local + script: examples/example.js + output: - - scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop): - * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s) + scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop): + * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s) -INFO[0000] key: plugin-name, value: k6-plugin-sql source=console +time="2024-10-18T09:06:52+02:00" level=info msg="name: extension-name, value: xk6-foo" source=console -running (00m00.1s), 0/1 VUs, 1 complete and 0 interrupted iterations -default ✓ [======================================] 1 VUs 00m00.0s/10m0s 1/1 iters, 1 per VU + data_received........: 0 B 0 B/s + data_sent............: 0 B 0 B/s + iteration_duration...: avg=496.46µs min=496.46µs med=496.46µs max=496.46µs p(90)=496.46µs p(95)=496.46µs + iterations...........: 1 550.030197/s - █ setup - █ teardown - - data_received........: 0 B 0 B/s - data_sent............: 0 B 0 B/s - iteration_duration...: avg=9.22ms min=19.39µs med=8.86ms max=18.8ms p(90)=16.81ms p(95)=17.8ms - iterations...........: 1 15.292228/s +running (00m00.0s), 0/1 VUs, 1 complete and 0 interrupted iterations +default ✓ [ 100% ] 1 VUs 00m00.0s/10m0s 1/1 iters, 1 per VU ``` -#### See also - -- [Load Testing SQL Databases with k6](https://k6.io/blog/load-testing-sql-databases-with-k6/) +
-### TLS Support -Presently, TLS support is available only for the MySQL driver. +## Build -To enable TLS support, call `sql.loadTLS` from the script, before calling `sql.open`. [mysql_secure_test.js](examples/mysql_secure_test.js) is an example. +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. -`sql.loadTLS` accepts the following options: +> [!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. -```javascript -sql.loadTLS({ - enableTLS: true, - insecureSkipTLSverify: true, - minVersion: sql.TLS_1_2, - // Possible values: sql.TLS_1_0, sql.TLS_1_1, sql.TLS_1_2, sql.TLS_1_3 - caCertFile: '/filepath/to/ca.pem', - clientCertFile: '/filepath/to/client-cert.pem', - clientKeyFile: '/filepath/to/client-key.pem', -}); +```bash +xk6 build --with github.com/grafana/xk6-sql@latest --with github.com/grafana/xk6-sql-driver-ramsql ``` -### Support for other RDBMSs +For more build options and how to use xk6, check out the [xk6 documentation](https://github.com/grafana/xk6). -Note that this project is not accepting support for additional SQL implementations -and RDBMSs. See the discussion in [issue #17](https://github.com/grafana/xk6-sql/issues/17) -for the reasoning. +Supported RDBMSs includes: `mysql`, `postgres`, `sqlite3`, `sqlserver`, `azuresql`, `clickhouse`. -There are however forks of this project that add additional support for: -- [Oracle](https://github.com/stefnedelchevbrady/xk6-sql-with-oracle) -- [Snowflake](https://github.com/libertymutual/xk6-sql) +Check the [xk6-sql-driver GitHub topic](https://github.com/topics/xk6-sql-driver) to discover database driver extensions. -You can build k6 binaries by simply specifying these project URLs in `xk6 build`. -E.g. `CGO_ENABLED=1 xk6 build --with github.com/stefnedelchevbrady/xk6-sql-with-oracle`. -Please report any issues with these extensions in their respective GitHub issue trackers, -and not in grafana/xk6-sql. +## Drivers +To use the xk6-sql extension, one or more database driver extensions should also be embedded. Database driver extension names typically start with the prefix `xk6-sql-driver-` followed by the name of the database, for example `xk6-sql-driver-mysql` is the name of the MySQL database driver extension. -## Docker +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. -For those who do not have a Go development environment available, or simply want -to run an extended version of `k6` as a container, Docker is an option to build -and run the application. +## Feedback -The following command will build a custom `k6` image incorporating the `xk6-sql` extension -built from the local source files. -```shell -docker build -t grafana/k6-for-sql:latest . -``` -Using this image, you may then execute the [examples/sqlite3_test.js](examples/sqlite3_test.js) script -by running the following command: -```shell -docker run -v $PWD:/scripts -it --rm grafana/k6-for-sql:latest run /scripts/examples/sqlite3_test.js -``` -For those on Mac or Linux, the `docker-run.sh` script simplifies the command: -```shell -./docker-run.sh examples/sqlite3_test.js -``` +If you find the **xk6-sql** extension useful, please star the repo. The number of stars will affect the time allocated for maintenance. + +[![Stargazers over time](https://starchart.cc/grafana/xk6-sql.svg?variant=adaptive)](https://starchart.cc/grafana/xk6-sql) + +## Contribute + +If you want to contribute or help with the development of **xk6-sql**, start by reading [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/examples/example.txt b/examples/example.txt new file mode 100644 index 0000000..01121e6 --- /dev/null +++ b/examples/example.txt @@ -0,0 +1,24 @@ + + /\ Grafana /‾‾/ + /\ / \ |\ __ / / + / \/ \ | |/ / / ‾‾\ + / \ | ( | (‾) | + / __________ \ |_|\_\ \_____/ + + execution: local + script: examples/example.js + output: - + + scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop): + * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s) + +time="2024-10-18T09:06:52+02:00" level=info msg="name: extension-name, value: xk6-foo" source=console + + data_received........: 0 B 0 B/s + data_sent............: 0 B 0 B/s + iteration_duration...: avg=496.46µs min=496.46µs med=496.46µs max=496.46µs p(90)=496.46µs p(95)=496.46µs + iterations...........: 1 550.030197/s + + +running (00m00.0s), 0/1 VUs, 1 complete and 0 interrupted iterations +default ✓ [ 100% ] 1 VUs 00m00.0s/10m0s 1/1 iters, 1 per VU From 05123835849f2ac7f13b63735711c81441b9d441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 11:53:23 +0200 Subject: [PATCH 02/10] removed obsoloted files --- Dockerfile | 23 ----------------------- docker-run.sh | 14 -------------- 2 files changed, 37 deletions(-) delete mode 100644 Dockerfile delete mode 100755 docker-run.sh diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 4d118a4..0000000 --- a/Dockerfile +++ /dev/null @@ -1,23 +0,0 @@ -# Multi-stage build to generate custom k6 with extension -FROM golang:1.21.11-bookworm as builder - -WORKDIR /go/src/go.k6.io/k6 - -ADD . . - -RUN apt-get update -y && \ - apt-get install -y build-essential git - -RUN go install go.k6.io/xk6/cmd/xk6@latest - -RUN CGO_ENABLED=1 xk6 build \ - --with github.com/grafana/xk6-sql=. \ - --output /tmp/k6 - -FROM gcr.io/distroless/base-debian12 - -USER 12345:12345 - -COPY --from=builder /tmp/k6 /k6 - -ENTRYPOINT ["/k6"] diff --git a/docker-run.sh b/docker-run.sh deleted file mode 100755 index 716d2ff..0000000 --- a/docker-run.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env zsh - -set -e - -if [ $# -lt 1 ]; then - echo "Usage: ./docker-run.sh [additional k6 args]" - exit 1 -fi - -# By default, we're assuming you created the extended k6 image as "grafana/k6-for-sql:latest". -# If not, override the name on the command-line with `IMAGE_NAME=...`. -IMAGE_NAME=${IMAGE_NAME:="grafana/k6-for-sql:latest"} - -docker run -v $PWD:/scripts -it --rm $IMAGE_NAME run /scripts/$1 ${@:2} From 2fbd70c691addbe96052996845b7fdb7a9a7823f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 11:53:38 +0200 Subject: [PATCH 03/10] simplify gitginore --- .gitignore | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/.gitignore b/.gitignore index 3d0a55b..8cce6d5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,22 +1,3 @@ -# Binaries for programs and plugins -*.exe -*.exe~ -*.dll -*.so -*.dylib - -# Test binary, built with `go test -c` -*.test - -# Output of the go coverage tool, specifically when used with LiteIDE -*.out - -# Dependency directories (remove the comment below to include it) -# vendor/ -k6 -*.sqlite - -.idea/ -.DS_Store - -*test.db +/k6 +/k6.exe +/coverage.out From 345985999ddbd7a877ab9f2d38abdaf6ed2491ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:03:03 +0200 Subject: [PATCH 04/10] ci: simplify workflow --- .github/workflows/ci.yml | 20 ++++++---------- .github/workflows/{linter.yml => lint.yml} | 28 +++++++--------------- 2 files changed, 16 insertions(+), 32 deletions(-) rename .github/workflows/{linter.yml => lint.yml} (53%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5e8364e..ccfdc1d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,30 +1,24 @@ name: CI on: - # Enable manually triggering this workflow via the API or web UI workflow_dispatch: push: branches: - main - - master tags: - v* pull_request: -defaults: - run: - shell: bash - jobs: - build-with-xk6: + build: runs-on: ubuntu-latest steps: - - name: Checkout code + - name: Checkout uses: actions/checkout@v4 - - name: Install Go - uses: actions/setup-go@v4 + - name: Setup Go + uses: actions/setup-go@v5 with: - go-version: 1.21.x + go-version: 1.22.x - name: Check build run: | go version @@ -38,7 +32,7 @@ jobs: --with $MODULE_NAME="." ./k6ext version - test-go-versions: + test: strategy: fail-fast: false matrix: @@ -49,7 +43,7 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - name: Install Go ${{ matrix.go-version }} - uses: actions/setup-go@v4 + uses: actions/setup-go@v5 with: go-version: ${{ matrix.go-version }} - name: Run tests diff --git a/.github/workflows/linter.yml b/.github/workflows/lint.yml similarity index 53% rename from .github/workflows/linter.yml rename to .github/workflows/lint.yml index 81c276a..d745a46 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/lint.yml @@ -5,38 +5,28 @@ on: pull_request: jobs: - check-modules: + lint: runs-on: ubuntu-latest steps: - - name: Checkout code + - name: Checkout uses: actions/checkout@v4 - - name: Install Go - uses: actions/setup-go@v4 with: - go-version: 1.21.x + fetch-depth: 0 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: 1.22.x - name: Check module dependencies run: | go version test -z "$(go mod tidy && git status go.* --porcelain)" go mod verify - - lint: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: Install Go - uses: actions/setup-go@v4 - with: - go-version: 1.21.x - name: Retrieve golangci-lint version run: | - echo "Version=$(head -n 1 "${GITHUB_WORKSPACE}/.golangci.yml" | tr -d '# ')" >> $GITHUB_OUTPUT + echo "Version=$(head -n 1 .golangci.yml | tr -d '# ')" >> $GITHUB_OUTPUT id: version - name: golangci-lint - uses: golangci/golangci-lint-action@v3 + uses: golangci/golangci-lint-action@v6 with: version: ${{ steps.version.outputs.Version }} only-new-issues: true From d7763f7bc358d121ef2e1f5db44259e237c0c5ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:03:15 +0200 Subject: [PATCH 05/10] ci: configura dependabot --- .github/dependabot.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..62af309 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: + - package-ecosystem: "gomod" + directory: "/" + schedule: + interval: "weekly" + day: "sunday" + time: "16:00" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "sunday" + time: "16:00" From b1e42bcb6eb50da3d18afe9e92a79a641e45bb35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:03:40 +0200 Subject: [PATCH 06/10] chore: simplify dependencies --- go.mod | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/go.mod b/go.mod index d4b22e9..4eee6f4 100644 --- a/go.mod +++ b/go.mod @@ -2,14 +2,11 @@ module github.com/grafana/xk6-sql go 1.22 -require ( - github.com/stretchr/testify v1.9.0 - go.k6.io/k6 v0.54.0 -) - require ( github.com/grafana/sobek v0.0.0-20240927094302-19dd311f018f github.com/proullon/ramsql v0.1.4 + github.com/stretchr/testify v1.9.0 + go.k6.io/k6 v0.54.0 ) require ( From 1ba640f51921fe85e877b416824593a7c3cd2d53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:04:18 +0200 Subject: [PATCH 07/10] docs: document contributing tasks --- CONTRIBUTING.md | 124 +++++++++++++++++++++++++++++++++++++----------- Makefile | 25 +++++----- 2 files changed, 109 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3b71a9..8514f94 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,32 +4,84 @@ Thank you for your interest in contributing to **xk6-sql**! Before you begin, make sure to familiarize yourself with the [Code of Conduct](CODE_OF_CONDUCT.md). If you've previously contributed to other open source project, you may recognize it as the classic [Contributor Covenant](https://contributor-covenant.org/). +If you want to chat with the team or the community, you can [join our community forums](https://community.grafana.com/c/grafana-k6). + +### Filing issues + +Don't be afraid to file issues! Nobody can fix a bug we don't know exists, or add a feature we didn't think of. + +The worst that can happen is that someone closes it and points you in the right direction. + +That said, "how do I..."-type questions are often more suited for [community forums](https://community.grafana.com/c/grafana-k6). + +### Contributing code + +If you'd like to contribute code, this is the basic procedure. + +1. Find an issue you'd like to fix. If there is none already, or you'd like to add a feature, please open one, and we can talk about how to do it. Out of respect for your time, please start a discussion regarding any bigger contributions either in a GitHub Issue, in the community forums **before** you get started on the implementation. + + Remember, there's more to software development than code; if it's not properly planned, stuff gets messy real fast. + +2. Create a fork and open a feature branch - `feature/my-cool-feature` is the classic way to name these, but it really doesn't matter. + +3. Create a pull request! + +4. We will discuss implementation details until everyone is happy, then a maintainer will merge it. + ## Prerequisites -- [Go toolchain](https://go101.org/article/go-toolchain.html) -- Git -- If you're using SQLite, a build toolchain for your system that includes `gcc` or - another C compiler. On Debian and derivatives install the `build-essential` - package. On Windows you can use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/). - Make sure that `gcc` is in your `PATH`. -- The tools listed in the [tools] section. It is advisable to first install the [cdo] tool, which can be used to easily perform the tasks described here. The [cdo] tool can most conveniently be installed using the [eget] tool. +Prerequisites are listed in the [tools] section in addition to the [go toolchain](https://go101.org/article/go-toolchain.html) and [git](https://git-scm.com/) CLI. + +### Special cases + +If the database driver uses shared library, a build toolchain for your system that includes `gcc` or another C compiler. On Debian and derivatives install the `build-essential` package. On Windows you can use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/). Make sure that `gcc` is in your `PATH`. + +The `Makefile` is generated from the task list defined in the `CONTRIBUTING.md` file using the [cdo] tool. If the contribution is made to the task list, the `Makefile` must be regenerated, which is why the [cdo] tool is needed. The [cdo] tool can most conveniently be installed using the [eget] tool. ```bash eget szkiba/cdo ``` -The [cdo] tool can then be used to perform the tasks described in the following sections. +[cdo]: https://github.com/szkiba/cdo +[eget]: https://github.com/zyedidia/eget + +## Tasks + +The tasks defined here can be executed manually or conveniently using the make or [cdo] tool. -Help about tasks: +**Help about tasks** +The command below lists the possible tasks. + +using make: + +```bash +make ``` + +using [cdo]: + +```bash cdo ``` -[cdo]: (https://github.com/szkiba/cdo) -[eget]: https://github.com/zyedidia/eget +**Execute task** + +Tasks are executed by passing the name of the task as a parameter. + +using make: -## tools - Install the required tools +```bash +make taskname +``` + +using [cdo]: + +```bash +cdo taskname +``` + +### tools - Install the required tools Contributing will require the use of some tools, which can be installed most easily with a well-configured [eget] tool. @@ -40,6 +92,7 @@ go install go.k6.io/xk6/cmd/xk6@latest ``` [tools]: (#tools---install-the-required-tools) +[xk6]: https://github.com/grafana/xk6 ### lint - Run the linter @@ -52,14 +105,18 @@ golangci-lint run ### test - Run the tests +The `go test` command is used to run the tests and generate the coverage report. + ```bash -go test -count 1 -race -coverprofile=coverage.out ./... +go test -count 1 -race -coverprofile=coverage.out -timeout 60s ./... ``` [test]: <#test---run-the-tests> ### coverage - View the test coverage report +The go `cover` tool should be used to display the coverage report in the browser. + Requires : [test] @@ -67,46 +124,59 @@ Requires go tool cover -html=coverage.out ``` -### build - Build a custom k6 with the extension +### build - Build custom k6 with extension + +The [xk6] tool is used to build the k6. In addition to the xk6-sql extension, the database driver extension you want to use should also be specified. ```bash -CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql +xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql ``` -[build]: <#build---build-a-custom-k6-with-the-extension> +[build]: <#build---build-custom-k6-with-extension> -### example - Run example +### example - Run the example + +Run the example embedded in `README.md` and save the output. ```bash ./k6 run examples/example.js > examples/example.txt 2>&1 ``` -### clean - Delete the build directory +### readme - Update README.md + +Update the example code and its output in `README.md`. ```bash -rm -rf build -rm -f ./k6 +mdcode update ``` -### format - Applies Go formatting to code +### clean - Clean the working directory + +Delete the work files created in the work directory (also included in .gitignore). ```bash -go fmt ./... +rm -f ./k6 ``` +[clean]: (#clean---clean-the-working-directory) + ### all - Clean build +Performs the most important tasks. It can be used to check whether the CI workflow will run successfully. + Requires -: clean, format, test, build +: [clean], [format], [test], [build] -### makefile - Generate Makefile +### format - Format the go source codes ```bash -cdo --makefile Makefile +go fmt ./... ``` -### readme - Update README.md +[format]: (#format---format-the-go-source-codes) + +### makefile - Generate the Makefile ```bash -mdcode update +cdo --makefile Makefile ``` diff --git a/Makefile b/Makefile index f807f20..c913976 100644 --- a/Makefile +++ b/Makefile @@ -9,13 +9,13 @@ __help__: @echo '' @echo 'Targets:' @echo ' all Clean build' - @echo ' build Build a custom k6 with the extension' - @echo ' clean Delete the build directory' + @echo ' build Build custom k6 with extension' + @echo ' clean Clean the working directory' @echo ' coverage View the test coverage report' - @echo ' example Run example' - @echo ' format Applies Go formatting to code' + @echo ' example Run the example' + @echo ' format Format the go source codes' @echo ' lint Run the linter' - @echo ' makefile Generate Makefile' + @echo ' makefile Generate the Makefile' @echo ' readme Update README.md' @echo ' test Run the tests' @echo ' tools Install the required tools' @@ -24,18 +24,17 @@ __help__: .PHONY: all all: clean format test build -# Build a custom k6 with the extension +# Build custom k6 with extension .PHONY: build build: @(\ - CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql;\ + xk6 build --with github.com/grafana/xk6-sql=. --with github.com/grafana/xk6-sql-driver-ramsql;\ ) -# Delete the build directory +# Clean the working directory .PHONY: clean clean: @(\ - rm -rf build;\ rm -f ./k6;\ ) @@ -46,14 +45,14 @@ coverage: test go tool cover -html=coverage.out;\ ) -# Run example +# Run the example .PHONY: example example: @(\ ./k6 run examples/example.js > examples/example.txt 2>&1;\ ) -# Applies Go formatting to code +# Format the go source codes .PHONY: format format: @(\ @@ -67,7 +66,7 @@ lint: golangci-lint run;\ ) -# Generate Makefile +# Generate the Makefile .PHONY: makefile makefile: @(\ @@ -85,7 +84,7 @@ readme: .PHONY: test test: @(\ - go test -count 1 -race -coverprofile=coverage.out ./...;\ + go test -count 1 -race -coverprofile=coverage.out -timeout 60s ./...;\ ) # Install the required tools From b2d572df51956b52f0df925a16f6bc3a633f6a57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:08:35 +0200 Subject: [PATCH 08/10] docs: fix links --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8514f94..862f6ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,7 +91,7 @@ eget -t 1.57.2 golangci/golangci-lint go install go.k6.io/xk6/cmd/xk6@latest ``` -[tools]: (#tools---install-the-required-tools) +[tools]: #tools---install-the-required-tools [xk6]: https://github.com/grafana/xk6 ### lint - Run the linter @@ -158,7 +158,7 @@ Delete the work files created in the work directory (also included in .gitignore rm -f ./k6 ``` -[clean]: (#clean---clean-the-working-directory) +[clean]: #clean---clean-the-working-directory ### all - Clean build @@ -173,7 +173,7 @@ Requires go fmt ./... ``` -[format]: (#format---format-the-go-source-codes) +[format]: #format---format-the-go-source-codes ### makefile - Generate the Makefile From e7c32612ac0c1ab8b1fc0b1fbe73d82fc20dcbc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:11:56 +0200 Subject: [PATCH 09/10] docs: add link to mdcode and golangci-lint tools --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 862f6ae..fd01915 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,11 +93,12 @@ go install go.k6.io/xk6/cmd/xk6@latest [tools]: #tools---install-the-required-tools [xk6]: https://github.com/grafana/xk6 +[mdcode]: https://github.com/szkiba/mdcode +[golangci-lint]: https://github.com/golangci/golangci-lint ### lint - Run the linter -The `golangci-lint` tool is used for static analysis of the source code. -It is advisable to run it before committing the changes. +The [golangci-lint] tool is used for static analysis of the source code. It is advisable to run it before committing the changes. ```bash golangci-lint run @@ -144,7 +145,7 @@ Run the example embedded in `README.md` and save the output. ### readme - Update README.md -Update the example code and its output in `README.md`. +Update the example code and its output in `README.md` using [mdcode] tool. ```bash mdcode update From 1da3365619d2d7560fe32ca5d2603e1ea7a53e0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Fri, 18 Oct 2024 16:28:42 +0200 Subject: [PATCH 10/10] docs: section about create driver --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 366432d..e0be56c 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,12 @@ To use the xk6-sql extension, one or more database driver extensions should also 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. +### Create driver + +Check the [grafana/xk6-sql-driver-ramsql](https://github.com/grafana/xk6-sql-driver-ramsql) template repository to create a new driver extension. This is a working driver extension with instructions in its README for customization. + +[Postgres driver extension](https://github.com/grafana/xk6-sql-driver-postgres) and [MySQL driver extension](https://github.com/grafana/xk6-sql-driver-mysql) are also good examples. + ## Feedback If you find the **xk6-sql** extension useful, please star the repo. The number of stars will affect the time allocated for maintenance.