/vsql-install-server

name: vsql-install-server
description: >
  Get a working VillageSQL server on this machine and prove it works —
  choose an install path (installer, Docker, or source), start the server,
  connect, load a bundled extension, and call one of its functions. Also
  covers reconnecting to a server that is already running. VillageSQL is a
  drop-in replacement for MySQL that adds extensions. Use when
  a task needs a local MySQL server for development or tests, starts a new
  project on MySQL, ports a PostgreSQL application to MySQL, or needs
  something MySQL lacks: UUIDv7 or 16-byte UUID keys, LLM calls or
  embeddings in SQL, password hashing or encryption in SQL, IP/CIDR/MAC
  columns, HTTP calls from SQL, fuzzy or phonetic text matching, a strict
  boolean, currency codes, n-dimensional cubes, a REST or MCP endpoint over
  the database, or JWT login.
  Also use before vsql-extension-builder, or any time a VillageSQL server is
  needed and none is confirmed working.
argument-hint: "[installer|docker|source]"

VillageSQL Server Install and Verify

Do not skip to installing. A server is often already running, and a second one on the same port will fail to start.

Arguments

If invoked as `/vsql-install-server <path>` where `<path>` is `installer`, `docker`, or `source`, skip Step 1 and use that path.

Conventions used below

Commands are written against two shell variables so they stay correct when you change a name. Set them once and use them verbatim afterwards.

VSQL_CONTAINER=vsql        # Docker path only; any name you like
VSQL_SOCKET=/tmp/mysql.sock  # host paths only; replace with the real socket

Every `docker` command below uses `"$VSQL_CONTAINER"`. If you name the container something else, nothing needs re-editing.

Decide the client invocation once, too. It has two parts: where the client binary is, and whether a password is needed.

An installer build does **not** put the client on `PATH`, so a bare `mysql` gives `mysql: command not found`. Take the path from `credentials.txt`:

VSQL_CLIENT="$HOME/.villagesql/prebuilt/bin/mysql"  # installer, prebuilt
VSQL_CLIENT="$HOME/.villagesql/build/bin/mysql"     # installer, source build
VSQL_CLIENT=mysql                                   # Docker, or a client already on PATH

Every host client call below is written as `"$VSQL_CLIENT" -u root`; the Docker ones call `mysql` inside the image, where it is always on `PATH`. If your setup has a root password, add `-p<password>` to **every** one of them; an empty-password setup needs nothing extra. The client then prints `[Warning] Using a password on the command line interface can be insecure.` on stderr — that warning is not output from your statement.

Keep the client *path* in that variable, never a whole command. zsh — the default shell on macOS — does not word-split an unquoted expansion, so a variable holding `mysql -u root` is passed as a single argument: `exec: "mysql -u root": executable file not found in $PATH`.

For Docker, prefix the call with the exec: `docker exec "$VSQL_CONTAINER" "$VSQL_CLIENT" -u root`.

Error messages are quoted below as the server sends them. `mysql -e` appends ` at line 1`, so a real line reads `ERROR 1064 (42000) at line 1: ...`.

Step 0 — Is a server already running?

**Skip this entirely on the Docker path.** A container you are about to create has no server in it yet, and running this check inside a still-initializing container reports "nothing running" a few seconds before a server appears. Step 0 is about a host install.

pgrep -l mysqld

If a PID comes back, read its actual arguments rather than assuming the defaults. On macOS `pgrep -a` does not print arguments; use `ps`:

ps -o command= -p <PID>

`[mysqld] <defunct>` means a dead process nobody reaped, not a server.

From the command line it prints, take the `--socket` and `--port` values, and the binary's own path — that directory holds the matching client, so set both variables from what you just read:

VSQL_SOCKET=<the --socket value>
VSQL_CLIENT=<dir of the mysqld path>/mysql

Do not assume `/tmp/mysql.sock`. A machine can have a source build, an installer build, and a Homebrew MySQL all present, and the socket is the only reliable way to reach the one that is actually up.

Confirm which server you reached before doing anything else:

"$VSQL_CLIENT" -u root --socket="$VSQL_SOCKET" -e "SELECT VERSION();"

A VillageSQL server reports a version like `8.4.11-villagesql-0.0.7`. If the version has no `villagesql` in it, you have reached a stock MySQL and should stop it or pick a different port before continuing.

If a working VillageSQL server is already up, skip to Step 4.

Step 1 — Choose an install path

| Path | Use when | Gets you | |---|---|---| | **Installer** | Default choice. You want to use VillageSQL, or build and test extensions. | Server, client, extension SDK, full MTR suite | | **Docker** | You want a disposable server, or a machine you do not want to install onto. | Server, client, extension SDK, C++ toolchain, `mysqltest`. **No `mysql-test-run.pl`.** | | **Source** | You are changing the server itself. | Everything, plus the server build tree |

State the Docker trade-off to the user before they pick it: you can build an extension and run a single test file by hand inside the container, but the `mysql-test-run.pl` orchestrator is absent, so a normal `--suite=` run is not possible there. If the goal is the full `vsql-extension-builder` workflow, recommend the installer. Details in Step 6.

Step 2 — Install

Installer

On a minimal Linux image, install the prerequisites before anything else. The installer does not install them:

apt-get update && apt-get install -y curl ca-certificates libaio1t64 libnuma1

`curl` and `ca-certificates` are needed to fetch the script at all — without them the command below fails with `curl: command not found`. `libaio1t64` and `libnuma1` are n