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

# vsql_currency extension for MySQL

> The vsql_currency extension adds a currency column type to MySQL that holds any of the 164 ISO 4217 codes in a single byte, case-insensitive on input.

A currency code column is usually a `CHAR(3)` that accepts any three letters,
including the ones that are not currencies. `vsql_currency` adds a `currency`
type that holds the 164 ISO 4217 codes pg-currency supports, in a single byte,
accepts them in any case, and prints them in the canonical uppercase form.

|                                   |                                                                         |
| --------------------------------- | ----------------------------------------------------------------------- |
| **Maintainer**                    | VillageSQL                                                              |
| **Source and full documentation** | [villagesql/vsql-currency](https://github.com/villagesql/vsql-currency) |
| **License**                       | GPL-2.0                                                                 |
| **Written in**                    | Rust                                                                    |

## Install

`vsql_currency` is not bundled with the server, so build it from the repository
first and copy the resulting `vsql_currency.veb` into the directory named by the
`veb_dir` system variable. Then install it:

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

Confirm it is there:

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

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_currency  |
+----------------+
```

The build instructions are in the
[repository](https://github.com/villagesql/vsql-currency).

## What it adds

### The currency type

```sql theme={null}
CREATE TABLE prices (
    sku    VARCHAR(8) PRIMARY KEY,
    amount DECIMAL(10,2),
    unit   currency
);
```

### Functions

| Function                       | Returns | What it does                                                 |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| `currency_count()`             | int     | How many codes the extension knows                           |
| `is_currency(code)`            | int     | 1 when the string is a valid ISO 4217 code, 0 when it is not |
| `supported_currencies(prefix)` | text    | The code list as a JSON array, narrowed by a prefix          |

## Example

Write the codes in any case, and read them back canonical and in order:

```sql theme={null}
INSERT INTO prices VALUES
    ('A-100', 19.99, 'usd'),
    ('A-101', 24.50, 'EUR'),
    ('A-102', 3100,  'jpy');

SELECT sku, amount, unit FROM prices ORDER BY unit;
```

```
+-------+---------+------+
| sku   | amount  | unit |
+-------+---------+------+
| A-101 |   24.50 | EUR  |
| A-102 | 3100.00 | JPY  |
| A-100 |   19.99 | USD  |
+-------+---------+------+
```

Check a code before you trust it, and list the ones you care about:

```sql theme={null}
SELECT currency_count() AS codes, is_currency('XYZ') AS xyz, is_currency('GBP') AS gbp;
```

```
+-------+------+------+
| codes | xyz  | gbp  |
+-------+------+------+
|   164 |    0 |    1 |
+-------+------+------+
```

```sql theme={null}
SELECT supported_currencies('C') AS starting_with_c;
```

```
+---------------------------------------------------------------------+
| starting_with_c                                                     |
+---------------------------------------------------------------------+
| ["CAD","CDF","CHF","CLP","CNY","COP","CRC","CUC","CUP","CVE","CZK"] |
+---------------------------------------------------------------------+
```

## See also

* [Choosing data types](/docs/guides/choosing-data-types) — when a narrower type earns its place
* [Install extensions](/docs/mysql-9.7/stable/install) — how `INSTALL EXTENSION` works and where the server looks for a bundle
* [Available extensions](/docs/mysql-9.7/stable/extensions) — the full catalog
* [villagesql/vsql-currency](https://github.com/villagesql/vsql-currency) — source, build instructions, and the known limitations