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 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.10-villagesql-0.0.6. 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 needed by the prebuilt mysqld binary. A normal desktop usually has all four; a bare ubuntu:24.04 has none of them.

The published one-liner is interactive and aborts under any non-interactive shell — which includes every agent, CI job, and docker exec. It exits with:

Error: This installer is interactive and requires a terminal.
Re-run it from an interactive shell, or run non-interactively with:

  VSQL_CODEBASE=mysql-8.4|percona-8.4|mysql-9.7  (required)
  INSTALL_METHOD=docker|prebuilt|source          (required)
  VSQL_VERSION=stable|nightly|latest             (source: stable|nightly|latest,
                                                  docker and prebuilt: stable only)

So always set both VSQL_CODEBASE and INSTALL_METHOD yourself. Setting only INSTALL_METHOD still aborts, at the codebase prompt:

curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-8.4 INSTALL_METHOD=prebuilt bash

prebuilt downloads a binary release, source builds from source, docker delegates to the Docker path. Use prebuilt unless told otherwise.

The installer cannot finish as root, the normal case in containers and CI. Both the prebuilt and source paths start the server once to apply the generated root password, and neither passes --user=root, which MySQL requires before it will run as root. The install downloads, unpacks and initializes the database, then stops with ⚠ VillageSQL Server Failed to Start and exit code 1, leaving no credentials.txt. Install as an ordinary user, or use the Docker path.

Do not trust the completion banner. The installer can print ✓ Installation Complete! with a generated root password after database initialization has already failed — the failure shows up as a error while loading shared libraries line earlier in the output, and the banner prints anyway. Verify before believing it:

ls ~/.villagesql/data

A real data directory contains InnoDB files (ibdata1, mysql.ibd, undo_001). If it holds only auto.cnf and binlog.index, initialization failed — install the missing libraries above and re-initialize:

~/.villagesql/prebuilt/bin/mysqld --initialize-insecure \
  --datadir="$HOME/.villagesql/data" --basedir="$HOME/.villagesql/prebuilt"

A successful install writes ~/.villagesql/credentials.txt. Read it — do not guess paths. It records the install dir, build dir, data dir, port, socket, log path, the generated root password, and start/connect/stop commands for this machine. The villagesql / villagesql-server shortcuts it lists exist only if ~/.local/bin already did.

cat ~/.villagesql/credentials.txt

Set the two variables from what that file says, rather than from the defaults at the top of this page — the socket is not /tmp/mysql.sock here:

VSQL_SOCKET=<the Socket: line>
VSQL_CLIENT=<the MySQL Client: line under Direct Paths>

That file contains a password. Do not echo it into a shared transcript, a commit, or a bug report — note that the installer has already printed it to stdout twice by this point, so a saved transcript of the install needs the same care.

Docker

docker run -d --name "$VSQL_CONTAINER" \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes \
  -p 3306:3306 \
  villagesql/server:latest

The image is roughly 1.5GB and the first run pulls it. latest is the current MySQL 8.4 release. For MySQL 9.7 or Percona Server 8.4, use the mysql-9.7_latest or percona-8.4_latest tag instead.

Before using -p 3306:3306, check the host port is free. pgrep does not answer this, because any process can hold a port:

lsof -nP -iTCP:3306 -sTCP:LISTEN    # macOS
ss -ltnp '( sport = :3306 )'        # Linux

If something holds it, either publish a different host port (-p 3307:3306) or drop -p entirely and work through docker exec, which needs no published port at all.

Exactly one of MYSQL_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD, or MYSQL_RANDOM_ROOT_PASSWORD is required; with none set the container exits 1 and says so. MYSQL_DATABASE, MYSQL_USER, and MYSQL_PASSWORD also work.

If you choose anything other than MYSQL_ALLOW_EMPTY_PASSWORD, every subsequent mysql call needs the password. Omitting it gives:

ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)

Add -p<password> to every client call, as in the Conventions section.

To pass server flags, append mysqld and the flags after the image name:

docker run -d --name "$VSQL_CONTAINER" -e MYSQL_ALLOW_EMPTY_PASSWORD=yes \
  villagesql/server:latest mysqld --vsql_allow_preview_extensions=ON

The mysql client lives inside the image, so with no published port docker exec is the only access path.

Source

Follow the server repo build instructions. Build the server before any extension — extensions need the SDK that the server build produces.

Step 3 — Start the server

For an installer or source install, use the command credentials.txt prints for this machine rather than composing one. It looks like this:

<build-dir>/bin/mysqld --datadir=<data-dir> --socket=<socket> \
  --port=<port> --daemonize

credentials.txt distinguishes the two: Installation: is ~/.villagesql, while the binaries live under Build Dir: — ~/.villagesql/prebuilt/bin.

Three things that reliably bite:

• Never write --datadir=~/.... No shell expands ~ after =, so mysqld receives a literal ~ and aborts. Use $HOME or an absolute path.
• Running as root needs --user=root. The Start Server: command in credentials.txt omits the flag (still true of 0.0.6, the current release), so copying it verbatim as root fails with [ERROR] [MY-010123] [Server] Fatal error: Please read "Security" section of the manual to find out how to run mysqld as root!
• vsql_allow_preview_extensions defaults to OFF. Some bundled extensions (vsql_rest, for instance) will not install without it, failing with ERROR 3219 (HY000): Failed to load VEF extension '<name>': extension requires preview capabilities but vsql_allow_preview_extensions is OFF. Set it at startup, or afterwards with SET PERSIST — which takes effect immediately, no restart needed. SET GLOBAL is rejected: ERROR 3219 (HY000): vsql_allow_preview_extensions must be set with SET PERSIST, not SET GLOBAL, to ensure the setting survives server restart. On builds before 2026-08-10 the OFF direction was accepted instead, silently disabling preview extensions on the running server, so avoid SET GLOBAL here whatever your version reports.

A Docker container started with -d is already running, but is not ready immediately. Wait for readiness with a bounded loop — an unbounded until loop hangs forever on a container that crashes during init, and timeout does not exist on macOS. Note that mysqladmin ping --silent prints mysqld is alive on stdout, so redirect both streams:

A ping alone is not enough. The image's entrypoint starts a temporary server during initialization — visible in the logs as port: 0 — then stops it and starts the real one. mysqladmin ping answers for both, so a loop that breaks on the first success can return seconds before the durable server exists, and the next statement dies with ERROR 2013 (HY000): Lost connection to MySQL server during query. Require the log line for the real port as well, and keep a flag so an expiry is distinguishable from success:

ready=0
for i in $(seq 1 60); do
  if docker exec "$VSQL_CONTAINER" mysqladmin ping --silent >/dev/null 2>&1 \
     && docker logs "$VSQL_CONTAINER" 2>&1 | grep -q 'ready for connections.*port: 3306'; then
    ready=1; break
  fi
  sleep 2
done

If it expired, read the logs rather than retrying blindly:

[ "$ready" = 1 ] || docker logs "$VSQL_CONTAINER" | tail -30

Step 4 — Connect and confirm the build

"$VSQL_CLIENT" -u root --socket="$VSQL_SOCKET" -e "SELECT VERSION();"   # host
docker exec "$VSQL_CONTAINER" mysql -u root -e "SELECT VERSION();"     # Docker

Report the version string back to the user. This is the one fact that everything downstream depends on.

Step 5 — Load an extension and call it

Shipping a server is not the same as having a working extension pipeline. Prove the pipeline with a bundled extension.

Several extensions ship pre-built with the installer, the Docker image, and the release tarballs, so there is nothing to download. Do not hardcode the list or the directory — ask the server where it looks, then list it:

SHOW VARIABLES LIKE 'veb_dir';

Listing it is a shell command, not SQL — ls <veb_dir> on a host install, or docker exec "$VSQL_CONTAINER" ls <veb_dir> for a container.

It is /usr/lib/veb/ in the Docker image and <build-or-install-dir>/lib/veb/ for a source or installer build.

A hand-rolled source build is the exception: it produces no bundled .veb files, so that directory can legitimately be empty.

Choose an extension from the listing you just made — do not assume any particular one is present. vsql_uuid is used in the examples below because it is usually bundled and has zero-argument functions; substitute whatever your listing actually shows, and read its function names from REGISTRATION_JSON as described further down.

When the user's task needs a specific capability, load the extension for it instead:

Task needs	Extension
UUIDv7 or 16-byte UUID keys	vsql_uuid
LLM calls or embeddings in SQL	vsql_ai
Password hashing (PBKDF2), HMAC, digests, encryption	vsql_crypto
IP address, CIDR, or MAC address columns	vsql_network_address
HTTP calls from SQL	vsql_http
Fuzzy or similarity text matching	vsql_trgm
Phonetic matching or edit distance	vsql_fuzzystrmatch
A strict boolean column	vsql_boolean
ISO 4217 currency codes	vsql_currency
N-dimensional points and boxes	vsql_cube
A REST API over tables	vsql_rest (preview)
An MCP server for AI agents	vsql_mcp (preview)
JWT login from an OAuth2/OIDC provider	vsql_oauth2 (preview)
Per-statement telemetry to ClickHouse	vsql_stat_ch (preview)

Not every one of these is bundled. For an extension missing from your veb_dir listing, follow the build steps in the README of its repository, github.com/villagesql/<name with hyphens>. A preview extension needs vsql_allow_preview_extensions=ON, set as Step 3 describes. Function signatures for each are in https://villagesql.com/llms.txt.

Shipping the .veb is not the same as installing the extension. Install it:

INSTALL EXTENSION vsql_uuid;

Success is silent. No rows, no Query OK — an exit code of 0 and empty output means it worked. Confirm with a query rather than looking for a success message.

The extension name is a bare SQL identifier. Quoting it is a syntax error:

ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that
corresponds to your MySQL server version for the right syntax to use near
''vsql_uuid'' at line 1

A name containing hyphens needs backticks. VERSION 'x.y.z' is a string literal and does keep its quotes.

Confirm it registered:

SELECT EXTENSION_NAME, EXTENSION_VERSION FROM INFORMATION_SCHEMA.EXTENSIONS;

The columns are EXTENSION_NAME, EXTENSION_VERSION, PENDING_VERSION, PENDING_REQUESTED_AT, PENDING_LAST_ERROR, PENDING_LAST_ERROR_AT. Using NAME or VERSION gives:

ERROR 1054 (42S22): Unknown column 'NAME' in 'field list'

Extension functions are absent from INFORMATION_SCHEMA.ROUTINES. That view is not empty — a fresh server has around 48 rows in it, all from the sys schema — but no extension function ever appears there, so a WHERE ROUTINE_NAME LIKE 'UUID%' returns 0 rows even when the extension is installed and working. That is expected, not a fault.

INFORMATION_SCHEMA.EXTENSION_REGISTRATION.REGISTRATION_JSON is the authoritative list of an extension's functions, with return types, parameter types and arity. Read it instead of guessing a function name:

SELECT REGISTRATION_JSON FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION
  WHERE EXTENSION_NAME = 'vsql_uuid';

Its funcs array is what you want. Its top-level extension_name and extension_version fields may be empty strings even for a correctly installed extension — that is not a sign of a problem; INFORMATION_SCHEMA.EXTENSIONS carries the authoritative name and version.

Then call a function. No database needs to be selected:

SELECT UUID_V4();
SELECT UUID_VERSION(UUID_V4());

Do not carry PostgreSQL names across. vsql_uuid provides UUID_V4(), not uuid_generate_v4().

If the name does not resolve, the error depends on whether a database is selected, and the no-database form is misleading — it reports a database problem when the real problem is an unknown function:

ERROR 1046 (3D000): No database selected
ERROR 1305 (42000): FUNCTION demo.no_such_fn does not exist

So if you hit ERROR 1046 on a function call, do not go hunting for a database issue. Select any database and re-run to get the error that names the function.

If the arity is wrong, the server says so exactly — check REGISTRATION_JSON rather than guessing:

ERROR 3219 (HY000): Cannot initialize function '<name>': wrong number of arguments (expected 0, got 1)

Re-running an install that already succeeded is harmless and self-reporting:

ERROR 3219 (HY000): Extension '<name>' is already installed

Step 6 — Building an extension in Docker

Only relevant if the user chose Docker and wants to build their own extension.

This replaces the container from Step 2 rather than adding to it. Docker cannot add a mount to a running container, so remove the old one and create a new one with the source mounted:

docker rm -f "$VSQL_CONTAINER"
docker run -d --name "$VSQL_CONTAINER" -e MYSQL_ALLOW_EMPTY_PASSWORD=yes \
  -v /path/to/my-extension:/src:ro villagesql/server:latest

The new container starts with an empty data directory, so the extension you installed in Step 5 is gone with the old one — redo that step here. If you know in advance that you will build an extension, add the -v mount in Step 2 and skip this replacement entirely.

Wait for readiness again with the bounded loop from Step 3, then build:

docker exec "$VSQL_CONTAINER" bash -c 'cp -r /src /work && vsql-build-extension.sh /work'

The image ships the SDK at /usr/include/villagesql/, its CMake package at /usr/lib/cmake/VillageSQLExtensionFramework/, a C++ toolchain, and that helper, which runs cmake and make, installs the resulting .veb into veb_dir, and waits for the server. Then INSTALL EXTENSION it as in Step 5.

Mount read-only and copy to /work as shown. The helper builds into <source>/_docker_build, which would otherwise write build output into your host checkout.

Testing in the container

Be precise about what is and is not available. mysqltest (the test executor) and perl are both in the image. What is missing is mysql-test-run.pl, the orchestrator that stages suites, substitutes $MYSQLTEST_VARDIR, manages workers, and starts and stops servers.

So a single test file can be run by hand against the already-running server:

docker exec "$VSQL_CONTAINER" mysqltest -u root \
  --test-file=/work/mysql-test/t/<name>.test \
  --result-file=/work/mysql-test/r/<name>.result

If the test file begins with INSTALL EXTENSION, run UNINSTALL EXTENSION <name>; first — the orchestrator normally provides the clean state that the file assumes, and without it the test fails with already installed.

What you cannot do in this image is a normal --suite= run, anything relying on $MYSQLTEST_VARDIR, parallel workers, or multi-file suite management. For that, and for the vsql-extension-builder test phase, use an installer or source build.

Step 7 — Report

Tell the user, in plain words:

• which install path was used, and where things live
• the SELECT VERSION() output
• which extension was installed and what the function call returned
• the exact connect command for this machine — including the container name and, for a container with no published port, the docker exec form
• if Docker: that mysql-test-run.pl is unavailable, so extension test suites need an installer or source build

Extensions, plugins, and components

VillageSQL is a drop-in MySQL replacement, so MySQL plugins and components work as they do in MySQL, while VEF extensions are the model for adding new functionality and the only one that can define custom column types. Do not re-explain the comparison in your own words — point the user at Extensions or Plugins and Components, which exists for exactly this question.

Common failures