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

# Installing Extensions

> How to add new capabilities to VillageSQL using extensions.

Install VillageSQL extensions to add custom types, functions, and capabilities to your database.

## Command Syntax

```sql theme={null}
INSTALL EXTENSION extension_name;
```

<Info>
  Extensions are distributed as `.veb` (VillageSQL Extension Bundle) files containing compiled libraries and metadata.
</Info>

### Extension Naming Conventions

VillageSQL uses different naming conventions in different contexts:

* **SQL commands:** Use underscores: `INSTALL EXTENSION vsql_uuid`
* **Repository names:** Use hyphens: `github.com/villagesql/vsql-uuid`
* **File names:** Use underscores: `vsql_uuid.veb`
* **manifest.json:** Use underscores to match SQL: `"name": "vsql_uuid"`

**Example:**

```bash theme={null}
# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# But .veb file uses underscores
ls vsql_uuid.veb

# Install with underscores (no quotes)
INSTALL EXTENSION vsql_uuid;
```

## Prerequisites

* Running VillageSQL Server instance
* Administrative access (root or equivalent)

## Installing Built-in Extensions

Built-in extensions included with VillageSQL are already in the veb\_dir. Simply enable them:

```sql theme={null}
-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;
```

### Verify Installation

```sql theme={null}
-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

**Output:**

```
+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
+------------------+-------------------+
```

### Test Functionality

```sql theme={null}
-- Create a database first
CREATE DATABASE test_db;
USE test_db;

-- Test extension functions
CREATE TABLE test (id INT, value COMPLEX);
INSERT INTO test VALUES (1, '(3,4)');
SELECT complex_abs(value) FROM test;  -- Returns 5.0

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;
```

## Installing External Extensions

For extensions downloaded or built separately:

<Info>
  Your server must have `veb_dir` configured before you can install external extensions. See [Configuring veb\_dir](/docs/mysql-8.4/0.0.4/managing#configuring-veb_dir).
</Info>

### 1. Copy the .veb File

Find your server's extension directory, then copy the `.veb` file into it:

```sql theme={null}
-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';
```

```bash theme={null}
cp /path/to/my_extension.veb /path/to/veb_dir/
```

### 2. Install Extension

```sql theme={null}
INSTALL EXTENSION my_extension;
```

### 3. Verify Installation

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';
```

## Troubleshooting

| Issue                                 | Solution                                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Extension not found`                 | Verify the `.veb` file is in `veb_dir`: `SHOW VARIABLES LIKE 'veb_dir'`                  |
| `Permission denied`                   | Check file permissions: `chmod 644 extension.veb`                                        |
| `extension name mismatch`             | Extension's internal name doesn't match the `.veb` filename. Rebuild the extension.      |
| `vef_register not found`              | The `.veb` file doesn't export a valid VEF entry point. Rebuild against the correct SDK. |
| `vef_register returned an error: ...` | Extension registration failed. Read the appended message for details.                    |

For more troubleshooting, see [Managing Extensions](/docs/mysql-8.4/0.0.4/managing).

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Extensions" icon="sliders" href="/docs/mysql-8.4/0.0.4/managing">
    Monitor and troubleshoot installed extensions
  </Card>

  <Card title="Available Extensions" icon="list" href="/docs/extensions">
    Browse extensions you can install
  </Card>

  <Card title="Create Extensions" icon="code" href="/docs/mysql-8.4/0.0.4/create">
    Build your own extensions
  </Card>
</CardGroup>