# Running

Running ws4sqlite can be done via the commandline, and it's possible to specify its behaviour via commandline parameters.

### Databases, `id`'s and Config (Companion) Files

ws4sqlite behaviour when serving databases is configured with a mix of commandline parameters and naming conventions. You specify directly on the commandline the databases to serve, either specifying the path of the file (for file-based databases) or the id of the in-memory database. Then, for file paths, ws4sqlite will look for a ["companion" configuration file](/ws4sqlite/documentation/configuration-file.md) in YAML format that have the same base name of the database filename, but with `.yaml` extension. When present, it is used to load the serving parameters for that database.

For in-memory dbs, you indicate an id to be used for that database, followed - if needed - by the path of the companion file for the in-memory database, separated by a colon (`:`).

In both cases, if the companion file is not present, default values will be used.

For example, if you run ws4sqlite as such:

```bash
ws4sqlite --db ~/file1.db --mem-db mem1:~/mem1.yaml --mem-db mem2
```

It will:

* serve a db from `~/file1.db`, creating it if absent, with an id of `file1`;
* look for `~/file1.yaml`, and - if present - load from there the configuration for this db;
* serve a db from memory, with an id of `mem1`;
* load its configuration from `~/mem1.yaml`;
* serve a db from memory, with an id of `mem2`, and default configuration.

{% hint style="info" %}
Since version 0.11.3, any extension can be used database file. Before that version, only `.db` could be used.
{% endhint %}

### Commandline Parameters

This is a complete commandline for ws4sqlite:

```bash
ws4sqlite --bind-host 0.0.0.0 --port 12321 --db FILE_DB --mem-db MEM_DB_ID[:MEM_DB_CFG_FILE]
```

Of course, the usual `--help` and `--version` are supported. Let's discuss the other commandline parameters one by one.

#### `--bind-host`

Host to bind to. Defaults to `0.0.0.0`, meaning to accept connections from any local network interface. Different values are possible to restrict connections to a particular subnet.

#### `--port`

Port to use for incoming network communication. Defaults to `12321`.

#### `--db`

Can be repeated.

Specifies one or more file paths to load and serve as SQLite db's. It will use the base name (without the `.db` suffix) as the id of the database, to use in the URL of the [request](/ws4sqlite/documentation/requests.md) , and will look for a configuration/companion file in the same path, named `<id>.yaml`.

It is also possible to specify a companion file at a different path, by specifying it after a colon (`:`). Example: `--db myFile.db:/another/path/myFileConfig.yaml`.

#### `--mem-db`

Can be repeated.

Specifies one or more id for in-memory databases. Optionally, it's possible to specify also the path of the configuration file, after a colon (`:`).

See the example above for a clearer explanation.

#### `--serve-dir`

Specifies a directory to serve via the internal web server. See the [relevant docs page](/ws4sqlite/documentation/web-server.md).

### Output

ws4sqlite will parse the commandline and the (eventual) [config files](/ws4sqlite/documentation/configuration-file.md), attempt to open and connect to the various databases, creating their respective files as needed. Then it will output a summary of all the configurations, like this:

```
ws4sqlite x.y.z
- Serving directory '/my/web/contents'
- Serving database 'db1' from /data/db1.db?_journal=WAL
  + Parsed companion config file
  + Using WAL
  + Authentication enabled, with 1 credentials
  + Maintenance scheduled at 12:01 am
  + CORS Origin set to https://db1.myserver.it
- Serving database 'db2' from /data/db2.db?mode=ro&immutable=1&_query_only=1&_journal=WAL
  + Parsed companion config file
  + Using WAL
  + Read only
  + Strictly using only stored statements
  + With 2 stored statements
  + CORS Origin set to https://noi.sbertilla.it
- Web Service listening on 0.0.0.0:12321
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://germ.gitbook.io/ws4sqlite/documentation/running.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.