sql

README

xk6-sql

This is a k6 extension using the xk6 system.

Supported RDBMSs: mysql, postgres, sqlite3, sqlserver. See the tests directory for examples. Other RDBMSs are not supported, see details below.

Build

To build a k6 binary with this plugin, first ensure you have the prerequisites:

• Go toolchain
• 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. Make sure that gcc is in your PATH.
• Git

Then:

1. Install xk6:

go install go.k6.io/xk6/cmd/xk6@latest

1. Build the binary:

xk6 build --with github.com/grafana/xk6-sql

If you're using SQLite, ensure you have a C compiler installed (see the prerequisites note) and set CGO_ENABLED=1 in the environment:

CGO_ENABLED=1 xk6 build --with github.com/grafana/xk6-sql

On Windows this is done slightly differently:

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.

make

Once built, you can run your newly extended k6 using:

 ./k6 run tests/sqlite3_test.js

Example

// script.js
import sql from 'k6/x/sql';

const db = sql.open("sqlite3", "./test.db");

export function setup() {
  db.exec(`CREATE TABLE IF NOT EXISTS keyvalues (
           id integer PRIMARY KEY AUTOINCREMENT,
           key varchar NOT NULL,
           value varchar);`);
}

export function teardown() {
  db.close();
}

export default function () {
  db.exec("INSERT INTO keyvalues (key, value) VALUES('plugin-name', 'k6-plugin-sql');");

  let results = sql.query(db, "SELECT * FROM keyvalues;");
  for (const row of results) {
    console.log(`key: ${row.key}, value: ${row.value}`);
  }
}

Result output:

$ ./k6 run script.js

          /\      |‾‾| /‾‾/   /‾‾/
     /\  /  \     |  |/  /   /  /
    /  \/    \    |     (   /   ‾‾\
   /          \   |  |\  \ |  (‾)  |
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: /tmp/script.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)

INFO[0000] key: plugin-name, value: k6-plugin-sql        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

    █ 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

See also

• Load Testing SQL Databases with k6

Support for other RDBMSs

Note that this project is not accepting support for additional SQL implementations and RDBMSs. See the discussion in issue #17 for the reasoning.

There are however forks of this project that add additional support for:

• Oracle
• Snowflake

You can build k6 binaries by simply specifying these project URLs in xk6 build. E.g. CGO_ENABLED=1 xk6 build --with github.com/stefnedelchev/xk6-sql-with-oracle. Please report any issues with these extensions in their respective GitHub issue trackers, and not in grafana/xk6-sql.

Docker

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.

The following command will build a custom k6 image incorporating the xk6-sql extension built from the local source files.

docker build -t grafana/k6-for-sql:latest .

Using this image, you may then execute the tests/sqlite3_test.js script by running the following command:

docker run -v $PWD:/scripts -it --rm grafana/k6-for-sql:latest run /scripts/tests/sqlite3_test.js

For those on Mac or Linux, the docker-run.sh script simplifies the command:

./docker-run.sh tests/sqlite3_test.js

Documentation

Index

• type RootModule
  • func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance
• type SQL
  • func (sql *SQL) Exports() modules.Exports
  • func (*SQL) Open(database string, connectionString string) (*dbsql.DB, error)
  • func (*SQL) Query(db *dbsql.DB, query string, args ...interface{}) ([]keyValue, error)

Types

type RootModule

type RootModule struct{}

RootModule is the global module object type. It is instantiated once per test run and will be used to create `k6/x/sql` module instances for each VU.

func (*RootModule) NewModuleInstance

func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance

NewModuleInstance implements the modules.Module interface to return a new instance for each VU.

type SQL

type SQL struct {
	// contains filtered or unexported fields
}

SQL represents an instance of the SQL module for every VU.

func (*SQL) Exports

func (sql *SQL) Exports() modules.Exports

Exports implements the modules.Instance interface and returns the exports of the JS module.

func (*SQL) Open

func (*SQL) Open(database string, connectionString string) (*dbsql.DB, error)

Open establishes a connection to the specified database type using the provided connection string.

func (*SQL) Query

func (*SQL) Query(db *dbsql.DB, query string, args ...interface{}) ([]keyValue, error)

Query executes the provided query string against the database, while providing results as a slice of KeyValue instance(s) if available.