> ## 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
* **CMake** 3.14.6 or higher - Build system generator (macOS requires 3.19 or higher)
* **C++ Compiler** - GCC 10 or newer, or Clang 14 or newer
* **Build tools** - make, ninja, or equivalent
* **Development libraries** - OpenSSL, ncurses, pkg-config, bison, and other MySQL dependencies

### Install Dependencies

**Ubuntu/Debian:**

```bash theme={null}
sudo apt install bison build-essential cmake libaio-dev libncurses5-dev \
                 libssl-dev libtirpc-dev pkg-config zlib1g-dev
```

**macOS (using Homebrew):**

First, install Homebrew if you haven't already:

```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Then install dependencies:

```bash theme={null}
brew install bison cmake openssl@3 pkgconf
```

## 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: Configure with CMake

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

**Linux:**

```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
```

**macOS:**

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

# Configure with CMake
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=~/mysql -DWITH_SSL=system
```

> [!NOTE]
>
> **Linux users:** Use `$HOME` for absolute paths. **macOS users:** Use `~` (tilde) — except in the `mysqld` commands in Steps 4 and 5, which use quoted `"$HOME/..."` paths on both platforms. The shell does not expand a tilde that follows `=`, so `--datadir=~/mysql-data/data` reaches `mysqld` as a literal `~` directory name and it aborts; the quotes keep the path in one piece if your home directory name contains a space. `cmake` expands the tilde itself, so `-DCMAKE_INSTALL_PREFIX=~/mysql` above is fine. Replace the repository path with your actual clone location if different.

### CMake Options Explained

* `<path-to-repo>` - Path to the cloned VillageSQL repository (use `$HOME` on Linux, `~` on macOS)
* `-DWITH_DEBUG=1` - Enables debug symbols (recommended for development)
* `-DCMAKE_INSTALL_PREFIX=~/mysql` - Sets installation directory
* `-DWITH_SSL=system` - Uses system OpenSSL library (required on macOS)

### Additional CMake Options

**Production build without debug symbols:**

Linux:

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

macOS:

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

**With custom compilation comment:**

Linux:

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

macOS:

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

**Developer mode with stricter warnings:**

Linux:

```bash theme={null}
cmake $HOME/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```

macOS:

```bash theme={null}
cmake ~/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```

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

## Step 3: Compile the Code

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

**Build the server and client (recommended for development):**

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

The `mysql` target builds the client used to connect in
[Step 6](#step-6-connect-with-mysql-client); `make -j10 mysqld` alone builds
only the server, and Step 6 would then have no client to run.

**Build everything:**

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

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

**Linux:**

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

**macOS:**

```bash theme={null}
ls ~/build/villagesql/bin/mysqld ~/build/villagesql/bin/mysql
```

## Step 4: Initialize the Database

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

**Linux:**

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"
```

**macOS:**

Production (with generated password - recommended):

```bash theme={null}
mkdir -p ~/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 ~/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:

**Linux:**

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

**macOS:**

```bash theme={null}
ls ~/mysql-data/data/mysql
```

## Step 5: Start the Server

Start the VillageSQL server:

**Linux:**

```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"
```

**macOS:**

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

> [!TIP]
>
> The `--gdb` flag installs a `SIGINT` handler so Ctrl-C stops the server cleanly — useful when running interactively from a terminal. To run in the background, add `--daemonize` to the `mysqld` command.

## Step 6: Connect with MySQL Client

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

**Linux:**

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
```

**macOS:**

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

```bash theme={null}
~/build/villagesql/bin/mysql -u root
```

If using --initialize (with generated password):

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

You should see the MySQL prompt:

```
Welcome to the VillageSQL Server for MySQL monitor.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>
```

### Verify Installation

Check that you're running VillageSQL:

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

Development builds append the git commit hash to the version string:

```
8.4.10-villagesql-0.0.6-dev-9e0577bd0b6
```

## Step 7: 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:

**Linux:**

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

**macOS:**

```bash theme={null}
# Ctrl-D to exit
~/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/en/8.4/0.0.5/server-development.md).

## Troubleshooting

### Build Fails with Missing Dependencies

Install the required development packages for your platform. Check the error message for specific missing libraries.

### Server Won't Start

* Verify the data directory was initialized: `ls ~/mysql-data/data/`
* Check if another MySQL/VillageSQL instance is using port 3306
* Review error logs in `~/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

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

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

> [card] [Getting Started](https://villagesql.com/docs/en/8.4/0.0.5/index.md)
>
> Quick start guide for VillageSQL.


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