vsql-install-server

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:stable

The image is roughly 1.5GB and the first run pulls it. A locally present

villagesql/server:latest is a different tag and is not a substitute —

pull :stable explicitly if you need it.

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:stable 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.

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:stable

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

| Symptom | Cause |

|---|---|

| Installer aborts saying it requires a terminal | Expected under any agent, CI job, or docker exec. Set both VSQL_CODEBASE=mysql-8.4 and INSTALL_METHOD=prebuilt (or source/docker). |

| ✓ Installation Complete! but the server will not start | The banner can print over a failed initialization. Check ~/.villagesql/data for InnoDB files; install libaio1t64 and libnuma1 and re-initialize. |

| error while loading shared libraries: libaio.so.1t64 or libnuma.so.1 | Missing OS packages the installer neither checks nor installs. apt-get install -y libaio1t64 libnuma1. |

| Fatal error: Please read "Security" section ... run mysqld as root | Running as root without --user=root. |

| Server will not start, port in use | Something else holds the port. Find it with lsof -nP -iTCP:3306 -sTCP:LISTEN (macOS) or ss -ltnp (Linux); stop it or pick another port. |

| mysqld aborts complaining about the data directory | --datadir=~/... passed a literal ~. Use $HOME or an absolute path. |

| Connects, but version has no villagesql | You reached a stock MySQL. Re-check the socket from ps. |

| No such container: vsql | The container name in this skill is a placeholder. Set VSQL_CONTAINER and use it everywhere. |

| ERROR 1045 (28000): Access denied ... (using password: NO) | The container was started with a root password but the client call omits it. Add -p<password>. |

| mysql: command not found after an installer install | The client is not on PATH. Use the full path from credentials.txt — see VSQL_CLIENT in Conventions. |

| Readiness loop never returns | Container died during init. docker logs <name> \| tail -30. |

| ERROR 1064 on INSTALL EXTENSION | The extension name was quoted. It is a bare identifier. |

| ERROR 3219 (HY000): VEB file not found: <name>.veb | The .veb is not in veb_dir. List that directory and check the spelling. |

| Rebuilt an extension, still see old behaviour | The old .veb is still what the server loads. SHOW VARIABLES LIKE 'veb_dir' to find the directory the server actually reads, and put the rebuilt file there — copying it into lib/plugin does nothing. Check EXTENSION_VERSION in INFORMATION_SCHEMA.EXTENSIONS to confirm which build is live, and install with an explicit VERSION 'x.y.z' so a stale .veb fails loudly instead of silently. |

| ERROR 1046 (3D000): No database selected on a function call | Misleading. The function name did not resolve and there was no default schema to name in the error. USE any database and re-run to get ERROR 1305 naming the function. |

| Extension installed but its functions are missing from INFORMATION_SCHEMA.ROUTINES | Expected. VEF functions never appear there, though the view itself is not empty. Use INFORMATION_SCHEMA.EXTENSION_REGISTRATION. |

| INSTALL EXTENSION printed nothing | That is success. Confirm with INFORMATION_SCHEMA.EXTENSIONS. |