> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build from Source

> Compile VillageSQL Server for MySQL from source code and get started with extensions.

## Overview

Building VillageSQL from source gives you the latest features and allows you to customize the build for your specific environment.

## Prerequisites

Before you begin, ensure you have the following installed:

* **Git** - For cloning the repository
* **A supported platform** - Debian or Ubuntu Linux, or macOS with [Homebrew](https://brew.sh)

The repository ships a script that installs CMake and the development libraries the build needs. On Linux it also installs the compiler; on macOS the Xcode Command Line Tools provide it. Step 2 runs that script, so you do not
have to install those packages yourself.

## Step 1: Clone the Repository

Clone the VillageSQL Server repository from GitHub, and ask for the
`mysql-9.7` branch — the default branch builds MySQL 8.4. Clone into your home
directory so the CMake steps below work without modification:

```bash theme={null}
cd "$HOME"
git clone --depth 1 -b mysql-9.7 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

To build the exact code a release shipped, clone the tag that marks it instead
of the branch: `-b publish/mysql-9.7_0.0.7`.

> [!NOTE]
>
> The repository is several GB due to the MySQL codebase.

## Step 2: Install Build Dependencies

Run the setup script from the repository you just cloned. The script detects
your operating system and installs the packages the build needs:

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh
```

On Linux the script uses `apt-get` and asks for `sudo`. On macOS it uses
Homebrew. VillageSQL CI installs its build dependencies with the same script,
so the package list stays current with the build.

> [!NOTE]
>
> The script supports Debian or Ubuntu Linux and macOS. On another Linux
> distribution, read `villagesql/bld_tools/setup_linux_build_env.sh` and
> install the equivalent packages with your own package manager.

## Step 3: Configure with CMake

Create a build directory outside the repository and configure the project:

```bash theme={null}
# Create build directory (outside the repo)
mkdir -p "$HOME/build/villagesql"
cd "$HOME/build/villagesql"

# Configure with CMake
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1
```

On macOS, add the OpenSSL 3 directory to that command. Homebrew's unversioned
`openssl` is now OpenSSL 4, which the server does not build against:

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
  -DWITH_SSL="$(brew --prefix openssl@3)"
```

> [!NOTE]
>
> Paths use `$HOME` rather than `~` throughout, on both platforms. The shell only
> expands `~` at the start of a word, so `--datadir=~/mysql-data/data` reaches
> `mysqld` as a directory literally named `~` and the server aborts. Quoting
> `"$HOME/..."` also keeps the path in one piece if your home directory name
> contains a space. Replace the repository path with your actual clone location
> if different.

### CMake Options Explained

* `"$HOME/villagesql-server"` - Path to the cloned VillageSQL repository
* `-DWITH_DEBUG=1` - Builds with the DBUG facility and assertions, unoptimized (recommended for development)
* `-DWITH_SSL="$(brew --prefix openssl@3)"` - Points cmake at OpenSSL 3. Step 2 installs `openssl@3`. If you skipped Step 2, run `brew install openssl@3` first, because `brew --prefix openssl@3` prints a path even when the package is absent, and cmake then stops with `Wrong option or path for WITH_SSL=`.

### Additional CMake Options

**Production build:**

```bash theme={null}
cmake "$HOME/villagesql-server"
```

**With custom compilation comment:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```

> [!NOTE]
>
> If you need to reconfigure, clear the CMake cache first (run from within the build directory):
>
> ```bash theme={null}
> rm CMakeCache.txt
> ```

## Step 4: Compile the Code

Build VillageSQL using make with parallel compilation. From within the build directory:

**Build everything (recommended):**

```bash theme={null}
make -j10
```

This builds the server, the `mysql` client that
[Step 7](#step-7-connect-with-mysql-client) uses, the extension SDK, and the
example extensions' `.veb` files.

**Build the server and client only:**

```bash theme={null}
make -j10 mysqld mysql
```

This pair is faster and builds neither the extension SDK nor the example
`.veb` files, so `INSTALL EXTENSION vsql_complex` finds no bundle to install
and an extension build that passes `-DVillageSQL_BUILD_DIR` finds no SDK.

> [!TIP]
>
> Adjust the parallelism (`-j10`) based on your CPU cores. Subtract 2-4 from your total core count to keep your system responsive. For example, on a 12-core machine, use `-j10`.

When complete, verify the server and client binaries were built:

```bash theme={null}
ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"
```

## Step 5: Initialize the Database

Before starting the server for the first time, initialize the data directory:

Production (with generated password - recommended):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

Development (no password - optional):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

> [!NOTE]
>
> Use `--initialize` (with password) for production-like setups. Use `--initialize-insecure` (no password) only for local development and testing. When using `--initialize`, a temporary password will be generated and printed to the console: `A temporary password is generated for root@localhost: <password>`

Verify initialization succeeded by checking that the system databases were created:

```bash theme={null}
ls "$HOME/mysql-data/data/mysql"
```

## Step 6: Start the Server

Start the VillageSQL server:

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

**Running as root (Docker or sudo):**

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

> [!TIP]
>
> The `--gdb` flag unblocks `SIGINT`, so Ctrl-C stops the server when you run it from a terminal. It also suppresses the crash backtrace and cancels `--core-file`, so leave it out when you want a crash report. To run in the background, add `--daemonize` to the `mysqld` command.

## Step 7: Connect with MySQL Client

Open a new terminal and connect to the server using the MySQL client:

If using --initialize-insecure (no password):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root
```

If using --initialize (with generated password):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root -p
# Enter the temporary password printed during initialization
```

You should see the MySQL prompt:

```
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version> Source distribution

mysql>
```

### Change Root Password

If you used `--initialize`, change the temporary password:

```sql theme={null}
SET PASSWORD = 'your-secure-password';
```

### Verify Installation

Check that you're running VillageSQL:

```sql theme={null}
SELECT VERSION();
```

Development builds include the git commit hash in the version string:

```
9.7.2-villagesql-0.0.7-dev-533ab4b58d2-debug
```

## Step 8: Set Up Users and Database

### Create a Development User

For daily development, create a non-root user:

```sql theme={null}
-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;
```

Exit and reconnect as your new user:

```bash theme={null}
# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p
```

### Create a Database

```sql theme={null}
CREATE DATABASE my_database;
USE my_database;
```

> [!TIP]
>
> Connect to a specific database: `"$HOME/build/villagesql/bin/mysql" -u developer -p -D my_database`

## Step 9: Run the Tests

Verify the build with the VillageSQL test suite, from the build directory. Run the tests as an ordinary user: as root, the test runner skips some tests, and one of them fails.

```bash theme={null}
cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto
```

`--nounit-tests` skips the upstream MySQL unit tests, which include known failures. Run the VillageSQL unit tests separately:

```bash theme={null}
make -j10 villagesql-unit-tests && ctest -L villagesql
```

A failing test makes either command exit non-zero.

For GDB debugging, running individual tests, re-recording expected results, and contributing to the server codebase, see the [Server Development Guide](https://villagesql.com/docs/en/9.7/dev/server-development.md).

## Building Native Packages (RPM/DEB)

`villagesql/bld_tools/build_deb.sh` and `build_rpm.sh` build a Debian or RPM
package straight from the source tree, for installing with your package
manager instead of following the manual steps above. Neither needs a prior
CMake configure — both derive the package version from the `VSQL_VERSION` and
`MYSQL_VERSION` files at the repository root. With Steps 1-2 already done,
install the packaging tools and the build dependencies Step 2 leaves out — on
Debian/Ubuntu `dpkg-dev`, `debhelper`, `libsystemd-dev`, and `systemd-dev`;
on Enterprise Linux `rpm-build` — then run one from the repository root:

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/build_deb.sh   # writes to ./debs
# or
villagesql/bld_tools/build_rpm.sh   # writes to ./rpms
```

According to [villagesql-server#931](https://github.com/villagesql/villagesql-server/pull/931),
which added this tooling, the resulting package takes over an existing MySQL
install on the target host rather than installing alongside one.

## Troubleshooting

### Build Fails with Missing Dependencies

Run the setup script again. [Step 3](#step-3-configure-with-cmake) leaves you in
the build directory, so give the script its absolute path:

```bash theme={null}
"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"
```

Check the error message for the specific missing library.

### Server Won't Start

* Verify the data directory was initialized: `ls "$HOME/mysql-data/data/"`
* Check if another MySQL/VillageSQL instance is using port 3306
* Read the messages that `mysqld` prints in its terminal, or start it with `--log-error="$HOME/mysql-data/error.log"` and read that file

### Extension Installation Fails

* Ensure the extension `.veb` file exists in the `veb_dir` directory (`$HOME/build/villagesql/lib/veb` for a source build) and that its library is named `<extension_name>.so` on Linux and macOS
* Check that VillageSQL has the necessary permissions to load extensions
* Verify the extension name and .veb filename are correct

## Next Steps

> [card] [Using Extensions](https://villagesql.com/docs/en/extensions/install.md)
>
> Learn how to install, update, and manage VillageSQL extensions.

> [card] [Creating Extensions](https://villagesql.com/docs/en/extensions/build/create.md)
>
> Build your own custom extensions for VillageSQL.

> [card] [Install](https://villagesql.com/docs/en/9.7/dev/install-server.md)
>
> Quick start guide for VillageSQL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.