<commit_before># sqlquest

Ever wanted to go on an adventure but ended up taking an arrow to the knee?
No worries, sqlquest has your back!

## Purpose

sqlquest is meant to be a brutally simple SQL job DSL/runner. It's written in
coffeescript and is designed to be easy enough to use that non-programmers
can make use of it with little training, and engineers can use it for complex
tasks. You can have your coffee and drink it too.

## Usage

sqlquest is meant to be used from an install in another project. The idea is
that you'll create your own 'myawesomequests' package. Example:

```
$ mkdir myawesomequests
$ cd myawesomequests
$ npm init
... follow instructions
$ npm install --save sqlquest
$ ln -s node_modules/.bin/sqlquest sqlquest
```

With this symlink, you can run sqlquest from the top level of your project.

Create a directory called `quests/`. This is where you'll put all your quests.
Each quest is a directory (the name of the quest) with at a minimum either a
`.{coffee,js}` file or a `sql/<questname>.sql` file.

You can run quests like so:

```
$ ./sqlquest awesomequest
```

This will run the quest in `quests/awesomequest/`.

## Quests

So how do you go on these damned quests? Well, we have a DSL for that!

Create a file, `quests/awesomequest/sql/awesome.sql`:

```sql
CREATE TABLE numbers (
  n integer
);

INSERT INTO TABLE numbers VALUES
  (1),
  (2),
  (3),
  (4);

SELECT * FROM numbers
WHERE a_number > {{min}};
```

Now create a file called `quests/awesomequest/awesome.coffee`

```coffee
Quest = require 'sqlquest'

module.exports =
class AwesomeQuest extends Quest
  adventure: ->
    @sql file: 'awesome.sql', {min: @opts.min}
```

Now you can run your **awesome** quest like so:

```
$ ./sqlquest awesomequest -u myuser -H my.db.com -d mydb -- --min 2
```

You should now see sqlquest running each block of sql in your `awesome.sql` file
one by one, outputting the queries and their execution times. Since we passed an
object as the second arg to `@sql` the sql is assumed to contain mustache
syntax like `{{variable}}` which will be filled in with the object's data.

If ya really really wanted, you could just embed the sql in the file itself:

```coffee
Quest = require 'sqlquest'
<commit_msg>Add docs on passing a connection URL<commit_after># sqlquest

Ever wanted to go on an adventure but ended up taking an arrow to the knee?
No worries, sqlquest has your back!

## Purpose

sqlquest is meant to be a brutally simple SQL job DSL/runner. It's written in
coffeescript and is designed to be easy enough to use that non-programmers
can make use of it with little training, and engineers can use it for complex
tasks. You can have your coffee and drink it too.

## Usage

sqlquest is meant to be used from an install in another project. The idea is
that you'll create your own 'myawesomequests' package. Example:

```
$ mkdir myawesomequests
$ cd myawesomequests
$ npm init
... follow instructions
$ npm install --save sqlquest
$ ln -s node_modules/.bin/sqlquest sqlquest
```

With this symlink, you can run sqlquest from the top level of your project.

Create a directory called `quests/`. This is where you'll put all your quests.
Each quest is a directory (the name of the quest) with at a minimum either a
`.{coffee,js}` file or a `sql/<questname>.sql` file.

You can run quests like so:

```
$ ./sqlquest awesomequest
```

This will run the quest in `quests/awesomequest/`.

## Quests

So how do you go on these damned quests? Well, we have a DSL for that!

Create a file, `quests/awesomequest/sql/awesome.sql`:

```sql
CREATE TABLE numbers (
  n integer
);

INSERT INTO TABLE numbers VALUES
  (1),
  (2),
  (3),
  (4);

SELECT * FROM numbers
WHERE a_number > {{min}};
```

Now create a file called `quests/awesomequest/awesome.coffee`

```coffee
Quest = require 'sqlquest'

module.exports =
class AwesomeQuest extends Quest
  adventure: ->
    @sql file: 'awesome.sql', {min: @opts.min}
```

Now you can run your **awesome** quest like so:

```
$ ./sqlquest awesomequest -u myuser -H my.db.com -d mydb -- --min 2
```

or

```
$ ./sqlquest awesomequest --url postgres://myuser:mypass@my.db.com/mydb -- --min 2
```

You should now see sqlquest running each block of sql in your `awesome.sql` file
one by one, outputting the queries and their execution times. Since we passed an
object as the second arg to `@sql` the sql is assumed to contain mustache
syntax like `{{variable}}` which will be filled in with the object's data.

If ya really really wanted, you could just embed the sql in the file itself:

```coffee
Quest = require 'sqlquest'

{'fraction_non_alphanumeric': 0.092176944868163, 'fraction_numerical': 0.002397036391370669, 'mean_word_length': 3.8366701791359326, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '157107', 'n_tokens_mistral': 1456, 'n_tokens_neox': 1390, 'n_words': 683}