> ## 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.

These steps build VillageSQL on upstream MySQL 8.4. VillageSQL also builds on
Percona Server as an alternative codebase — see the
[Percona Build](https://villagesql.com/docs/mysql-8.4/0.0.6/percona.md) page.

## 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 the compiler, CMake, and the
development libraries the build needs. 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. Clone into your home directory so the CMake steps below work without modification:

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

> [!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 -DCMAKE_INSTALL_PREFIX="$HOME/mysql"
```

> [!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

* `<path-to-repo>` - Path to the cloned VillageSQL repository
* `-DWITH_DEBUG=1` - Builds with the DBUG facility and assertions, unoptimized (recommended for development)
* `-DCMAKE_INSTALL_PREFIX="$HOME/mysql"` - Sets installation directory

### Additional CMake Options

**Production build:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
```

**With custom compilation comment:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
      -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"
```

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

If running as root (e.g., in Docker), MySQL requires the `--user=root` flag:

```bash theme={null}
# Initialize as root
"$HOME/build/villagesql/bin/mysqld" --user=root --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>
```

### Verify Installation

Check that you're running VillageSQL:

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

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

```
8.4.11-villagesql-0.0.6-dev-eac70667eb6
```

## Step 8: Set Up Users and Database

### Change Root Password

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

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

### 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: `mysql -u developer -p -D my_database`

For GDB debugging, running tests, and contributing to the server codebase, see the [Server Development Guide](https://villagesql.com/docs/mysql-8.4/0.0.6/server-development.md).

## 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
* Review error logs in `$HOME/mysql-data/data/*.err`

### Extension Installation Fails

* Ensure the extension library (`.so` on Linux, `.dylib` on macOS) exists in the build output
* Check that VillageSQL has the necessary permissions to load extensions
* Verify the extension name and .veb filename are correct

## Next Steps

> **[Using Extensions](https://villagesql.com/docs/mysql-8.4/0.0.6/install.md)**
>
> Learn how to install, update, and manage VillageSQL extensions.

> **[Creating Extensions](https://villagesql.com/docs/mysql-8.4/0.0.6/create.md)**
>
> Build your own custom extensions for VillageSQL.

> **[Getting Started](https://villagesql.com/docs/mysql-8.4/0.0.6/index.md)**
>
> Quick start guide for VillageSQL.


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