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.
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:
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.
If a PID comes back, read its actual arguments rather than assuming the
defaults. On macOS pgrep -a does not print arguments; use ps:
[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:
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:
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
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:
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:
So always set both VSQL_CODEBASE and INSTALL_METHOD yourself. Setting only
INSTALL_METHOD still aborts, at the codebase prompt:
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:
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:
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.
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:
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
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:
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:
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:
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:
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$HOMEor an absolute path. - Running as root needs
--user=root. TheStart Server:command incredentials.txtomits 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_extensionsdefaults toOFF. Some bundled extensions (vsql_rest, for instance) will not install without it, failing withERROR 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 withSET PERSIST— which takes effect immediately, no restart needed.SET GLOBALis 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 theOFFdirection was accepted instead, silently disabling preview extensions on the running server, so avoidSET GLOBALhere 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:
If it expired, read the logs rather than retrying blindly:
Step 4 — Connect and confirm the build
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:
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:
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:
A name containing hyphens needs backticks. VERSION 'x.y.z' is a string
literal and does keep its quotes.
Confirm it registered:
The columns are EXTENSION_NAME, EXTENSION_VERSION, PENDING_VERSION,
PENDING_REQUESTED_AT, PENDING_LAST_ERROR, PENDING_LAST_ERROR_AT. Using
NAME or VERSION gives:
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:
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:
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:
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:
Re-running an install that already succeeded is harmless and self-reporting:
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:
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:
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:
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 execform - if Docker: that
mysql-test-run.plis 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.
