docker: Improvements (#152)

- Added more detailed documentation for using docker.

- As ctrl+C doesn't forward the signal with `docker run`, you can now
use `exit` to exit the shell.

- Errors are now formatted correctly and do not cause the CLI to exit.

- Hopefully, this fixes a stdout bug where "vsql> " appears after the
input. Although, I cannot test this easily on macOS.

.github/workflows/ci.yml

@@ -5,10 +5,6 @@ on:
     paths-ignore:
       - "**.md"
       - "**.rst"
-  pull_request:
-    paths-ignore:
-      - "**.md"
-      - "**.rst"
 
 concurrency:
   group: ci-${{ github.event.pull_request.number || github.sha }}

cmd/vsql/cli.v

@@ -29,11 +29,22 @@ fn cli_command(cmd cli.Command) ! {
 
 	for {
 		print('vsql> ')
+		os.flush()
+
 		query := os.get_line()
 
+		// When running on Docker, ctrl+C doesn't always get passed through. Also,
+		// this provides another text based way to break out of the shell.
+		if query.trim_space() == 'exit' {
+			break
+		}
+
 		if query != '' {
 			start := time.ticks()
-			result := db.query(query)!
+			result := db.query(query) or {
+				print_error(err)
+				continue
+			}
 
 			mut total_rows := 0
 			for row in result {
@@ -59,3 +70,12 @@ fn cli_command(cmd cli.Command) ! {
 		println('')
 	}
 }
+
+fn print_error(err IError) {
+	if err.code() > 0 {
+		sqlstate := vsql.sqlstate_from_int(err.code())
+		println('${sqlstate}: ${err.msg()}\n')
+	} else {
+		println('ERROR: ${err}\n')
+	}
+}

docs/docker.rst

@@ -0,0 +1,68 @@
+Docker
+======
+
+.. contents::
+
+Docker is the easiest way to get up and running (if you have
+`Docker installed <https://docs.docker.com/get-docker/>`_.). Pull the latest
+stable version with:
+
+.. code-block:: sh
+
+   docker pull elliotchance/vsql:latest
+
+You can also use major (``0``), minor (``0.27``) or patch versions (``0.27.1``).
+View all versions on
+`hub.docker.com/repository/docker/elliotchance/vsql/tags <https://hub.docker.com/repository/docker/elliotchance/vsql/tags?page=1&ordering=last_updated>`_.
+
+CLI
+---
+
+Run the CLI directly:
+
+.. code-block:: sh
+
+   docker run --mount type=bind,source="$(pwd)",target=/db -it elliotchance/vsql:latest cli /db/mydb.vsql
+
+Modify ``source`` to where you want the host directory (it is the current
+directory by default). Exit the shell with ``exit``.
+
+**Important:** While it is possible to run vsql without using a mount, this is
+not recommended as it will leave the database file on the containers file
+system. This will cause the database file will be lost with the container.
+Although, sometimes this is the desired behavior:
+
+.. code-block:: sh
+
+   docker run -it elliotchance/vsql:latest cli mydb.vsql
+
+See :doc:`cli`.
+
+Server
+------
+
+Start the PostgreSQL-compatible server:
+
+.. code-block:: sh
+
+   docker run --mount type=bind,source="$(pwd)",target=/db -it elliotchance/vsql:latest server /db/mydb.vsql
+
+See :doc:`server`.
+
+Apple M1 Macs
+-------------
+
+If you're running on an M1 mac, you might see the following issue warning when
+running the container:
+
+.. code-block:: text
+
+   WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
+   GC Warning: getcontext failed: using another register retrieval method...
+
+It doesn't seem like this causes any issues, but if you want to suppress the
+message you can set ``DOCKER_DEFAULT_PLATFORM`` before running the container:
+
+.. code-block:: sh
+
+   export DOCKER_DEFAULT_PLATFORM=linux/amd64

docs/getting-started.rst

@@ -5,4 +5,5 @@ Getting Started
    :maxdepth: 1
 
    install.rst
+   docker.rst
    faq.rst

docs/install.rst

@@ -3,6 +3,8 @@ Installing & Updating
 
 There are lots of ways to install vsql depending on how you want to use it.
 
+.. contents::
+
 Docker
 ------
 
@@ -14,21 +16,7 @@ stable version with:
 
    docker pull elliotchance/vsql:latest
 
-You can also use major (``0``), minor (``0.27``) or patch versions (``0.27.1``).
-View all versions on
-`hub.docker.com/repository/docker/elliotchance/vsql/tags <https://hub.docker.com/repository/docker/elliotchance/vsql/tags?page=1&ordering=last_updated>`_.
-
-Run the CLI directly (see :doc:`cli`):
-
-.. code-block:: sh
-
-   docker run -it elliotchance/vsql:latest cli mydb.vsql
-
-Or, start the PostgreSQL-compatible server (see :doc:`server`):
-
-.. code-block:: sh
-
-   docker run -it elliotchance/vsql:latest server mydb.vsql
+See :doc:`docker` for more information.
 
 Prebuilt Binaries
 -----------------