Merge pull request #123 from grafana/122-connection-options-in-the-op…

…en-function

Connection options in the open function

.editorconfig

@@ -8,7 +8,7 @@ charset = utf-8
 trim_trailing_whitespace = false
 insert_final_newline = true
 
-[*.{yml,yaml,json,sh,bats}]
+[*.{js,ts,yml,yaml,json,sh,bats}]
 indent_size = 2
 trim_trailing_whitespace = true
 

index.d.ts

@@ -7,7 +7,7 @@
  * 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.
+ * which should be passed as a parameter of the {@link open} function.
  *
  * The driver module is typically available at `k6/x/sql/driver/FOO`,
  * where `FOO` is the name of the driver.
@@ -65,6 +65,7 @@ export as namespace sql;
  *
  * @param dirverID driver identification symbol, the default export of the driver module
  * @param dataSourceName driver-specific data source name, like a database name
+ * @param options connection related options
  *
  * @example
  *  ```ts file=examples/example.js
@@ -76,7 +77,74 @@ export as namespace sql;
  *  const db = sql.open(driver, "roster_db");
  * ```
  */
-export function open(dirverID: Symbol, dataSourceName: String): Database;
+export function open(
+  dirverID: Symbol,
+  dataSourceName: String,
+  options?: Options
+): Database;
+
+/**
+ * Connection-related options for the {@link open} function.
+ * @example
+ *  ```ts
+ *  import sql from "k6/x/sql";
+ *
+ *  // the actual database driver should be used instead of ramsql
+ *  import driver from "k6/x/sql/driver/ramsql";
+ *
+ *  const db = sql.open(driver, "roster_db", { conn_max_idle_time: "2s" });
+ * ```
+ */
+export interface Options {
+  /**
+   * Sets the maximum amount of time a connection may be idle.
+   * If 0, connections are not closed due to a connection's idle time.
+   * A duration string is a possibly signed sequence of decimal numbers,
+   * each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
+   * Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+   *
+   * @example
+   * ```ts
+   * const db = sql.open(driver, "roster_db", { conn_max_idle_time: "1h10m10s" });
+   * ```
+   */
+  conn_max_idle_time: string;
+  /**
+   * Sets the maximum amount of time a connection may be reused.
+   * If 0, connections are not closed due to a connection's age.
+   * A duration string is a possibly signed sequence of decimal numbers,
+   * each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
+   * Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+   *
+   * @example
+   * ```ts
+   * const db = sql.open(driver, "roster_db", { conn_max_lifetime: "10h" });
+   * ```
+   */
+  conn_max_lifetime: string;
+  /**
+   * Sets the maximum number of connections in the idle connection pool.
+   * If 0, no idle connections are retained.
+   * The default is currently 2.
+   *
+   * @example
+   * ```ts
+   * const db = sql.open(driver, "roster_db", { max_idle_conns: 3 });
+   * ```
+   */
+  max_idle_conns: number;
+  /**
+   * Sets the maximum number of open connections to the database.
+   * If 0, then there is no limit on the number of open connections.
+   * The default is 0 (unlimited).
+   *
+   * @example
+   * ```ts
+   * const db = sql.open(driver, "roster_db", { max_open_conns: 100 });
+   * ```
+   */
+  max_open_conns: number;
+}
 
 /**
  * Database is a database handle representing a pool of zero or more underlying connections.

releases/v1.0.3.md

@@ -2,6 +2,32 @@ xk6-sql `v1.0.3` is here 🎉!
 
 This release includes:
 
-Bugfixes:
+## New features
+
+- [Connection options in the open function](https://github.com/grafana/xk6-sql/issues/122): An optional options parameter can be used in `open()` to specify database connection-related options.
+
+    ```js
+    sql.open(driver, "roster_db", opts)
+    ```
+
+    Properties:
+    - `conn_max_idle_time`:  Sets the maximum amount of time a connection may be idle. If 0, connections are not closed due to a connection's idle time. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Example:
+        ```js
+        const db = sql.open(driver, "roster_db", { conn_max_idle_time: "1h10m10s" });
+        ```
+    - `conn_max_lifetime`: Sets the maximum amount of time a connection may be reused. If 0, connections are not closed due to a connection's age. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Example:
+        ```js
+        const db = sql.open(driver, "roster_db", { conn_max_lifetime: "10h" });
+        ```
+    - `max_idle_conns`: Sets the maximum number of connections in the idle connection pool. If 0, no idle connections are retained. The default is currently 2. Example:
+        ```js
+        const db = sql.open(driver, "roster_db", { max_idle_conns: 3 });
+        ```
+    - `max_open_conns`: Sets the maximum number of open connections to the database.  If 0, then there is no limit on the number of open connections. The default is 0 (unlimited). Example:
+        ```js
+        const db = sql.open(driver, "roster_db", { max_open_conns: 100 });
+        ```
+
+## Bugfixes
 
 - [Symbol type driver parameter support](https://github.com/grafana/xk6-sql/issues/120): The `open()` function now accepts `Symbol` (class) type driver ids in addition to the primitive symbol type. This is because when a driver is imported with the `require()` function, it is not a primitive symbol that is imported, but a `Symbol` class type. Also fixes [#115](https://github.com/grafana/xk6-sql/issues/115)

sql/module.go

@@ -76,7 +76,7 @@ func asSymbol(value sobek.Value) (*sobek.Symbol, bool) {
 
 // open establishes a connection to the specified database type using
 // the provided connection string.
-func (mod *module) Open(driverID sobek.Value, connectionString string) (*Database, error) {
+func (mod *module) Open(driverID sobek.Value, connectionString string, opts *options) (*Database, error) {
 	driverSym, ok := asSymbol(driverID)
 
 	if !ok {
@@ -93,6 +93,10 @@ func (mod *module) Open(driverID sobek.Value, connectionString string) (*Databas
 		return nil, err
 	}
 
+	if err = opts.apply(db); err != nil {
+		return nil, err
+	}
+
 	return &Database{db: db}, nil
 }
 

sql/module_test.go

@@ -12,11 +12,21 @@ import (
 //go:embed testdata/script.js
 var script string
 
+func TestMain(m *testing.M) {
+	sql.RegisterModule("ramsql")
+
+	m.Run()
+}
+
 // TestIntegration performs an integration test creating a ramsql database.
 func TestIntegration(t *testing.T) {
 	t.Parallel()
 
-	sql.RegisterModule("ramsql")
-
 	sqltest.RunScript(t, "ramsql", "testdb", script)
 }
+
+func TestOptions(t *testing.T) {
+	t.Parallel()
+
+	sqltest.RunScript(t, "ramsql", "testdb", `const db = sql.open(driver, connection, { conn_max_idle_time: "5s" });`)
+}

sql/options.go

@@ -0,0 +1,50 @@
+package sql
+
+import (
+	"database/sql"
+	"time"
+
+	"github.com/grafana/sobek"
+)
+
+// options represents connection related options for Open().
+type options struct {
+	ConnMaxIdleTime sobek.Value
+	ConnMaxLifetime sobek.Value
+	MaxIdleConns    sobek.Value
+	MaxOpenConns    sobek.Value
+}
+
+func (o *options) apply(db *sql.DB) error {
+	if o == nil {
+		return nil
+	}
+
+	if o.ConnMaxIdleTime != nil {
+		d, err := time.ParseDuration(o.ConnMaxIdleTime.String())
+		if err != nil {
+			return err
+		}
+
+		db.SetConnMaxIdleTime(d)
+	}
+
+	if o.ConnMaxLifetime != nil {
+		d, err := time.ParseDuration(o.ConnMaxLifetime.String())
+		if err != nil {
+			return err
+		}
+
+		db.SetConnMaxLifetime(d)
+	}
+
+	if o.MaxIdleConns != nil {
+		db.SetMaxIdleConns(int(o.MaxIdleConns.ToInteger()))
+	}
+
+	if o.MaxOpenConns != nil {
+		db.SetMaxOpenConns(int(o.MaxOpenConns.ToInteger()))
+	}
+
+	return nil
+}

sql/options_internal_test.go

@@ -0,0 +1,29 @@
+package sql
+
+import (
+	"database/sql"
+	"testing"
+
+	"github.com/grafana/sobek"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_options_apply(t *testing.T) {
+	t.Parallel()
+
+	db, err := sql.Open("ramsql", "foo")
+
+	require.NoError(t, err)
+
+	rt := sobek.New()
+
+	require.NoError(t, (&options{}).apply(db))
+	require.NoError(t, (&options{ConnMaxIdleTime: rt.ToValue("5s")}).apply(db))
+	require.NoError(t, (&options{ConnMaxLifetime: rt.ToValue("10m")}).apply(db))
+
+	require.NoError(t, (&options{MaxIdleConns: rt.ToValue(5)}).apply(db))
+	require.NoError(t, (&options{MaxOpenConns: rt.ToValue(10)}).apply(db))
+
+	require.Error(t, (&options{ConnMaxIdleTime: rt.ToValue("5g")}).apply(db))
+	require.Error(t, (&options{ConnMaxLifetime: rt.ToValue("10e")}).apply(db))
+}

sql/sql_internal_test.go

@@ -15,16 +15,16 @@ func TestOpen(t *testing.T) { //nolint: paralleltest
 	driver := RegisterDriver("ramsql")
 	require.NotNil(t, driver)
 
-	db, err := mod.Open(driver, "")
+	db, err := mod.Open(driver, "", nil)
 
 	require.NoError(t, err)
 	require.NotNil(t, db)
 
-	_, err = mod.Open(sobek.New().ToValue("foo"), "testdb") // not a Symbol
+	_, err = mod.Open(sobek.New().ToValue("foo"), "testdb", nil) // not a Symbol
 
 	require.Error(t, err)
 
-	_, err = mod.Open(sobek.NewSymbol("ramsql"), "testdb") // not a registered Symbol
+	_, err = mod.Open(sobek.NewSymbol("ramsql"), "testdb", nil) // not a registered Symbol
 
 	require.Error(t, err)
 }