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

# Add a PostgreSQL extension to pgxman

## Prerequisites

* Docker

## Initialize an buildkit file

```sh theme={null}
pgxman init
```

`init` is interactive and will prompt you about the extension you wish to
create.

This result is a manifest file named `extension.yaml`. The file serves as your
blueprint for building the extension.

## Writing the buildkit file

[Please refer to the full buildkit file specification for details](spec/buildkit). You'll
find a full documented example with all available fields, as well as documentation for the file.
You can also [review existing buildkits](https://github.com/pgxman/buildkit/tree/main/buildkit)
for examples on how to create a buildkit.

Most manifest files should follow the build instructions for the extension.
This may be as simple as `make && make install`, but others may be considerably
more complicated. Review the documentation for the extension for build
instructions and any required dependencies.

## Building the extension

Once you have a buildkit written, use pgxman to build the extension locally.
pgxman uses Docker to build the packages.

```sh theme={null}
pgxman build -f extension.yaml
```

This will package the extension files in the `out` directory:

```
$ tree out
out
├── linux_amd64
│   ├── debian
│   │   └── bookworm
│   │       ├── postgresql-13-pgxman-pgvector_0.5.0_amd64.deb
│   │       ├── postgresql-14-pgxman-pgvector_0.5.0_amd64.deb
│   │       └── postgresql-15-pgxman-pgvector_0.5.0_amd64.deb
│   └── ubuntu
│       └── jammy
│           ├── postgresql-13-pgxman-pgvector_0.5.0_amd64.deb
│           ├── postgresql-14-pgxman-pgvector_0.5.0_amd64.deb
│           └── postgresql-15-pgxman-pgvector_0.5.0_amd64.deb
└── linux_arm64
    ├── debian
    │   └── bookworm
    │       ├── postgresql-13-pgxman-pgvector_0.5.0_arm64.deb
    │       ├── postgresql-14-pgxman-pgvector_0.5.0_arm64.deb
    │       └── postgresql-15-pgxman-pgvector_0.5.0_arm64.deb
    └── ubuntu
        └── jammy
            ├── postgresql-13-pgxman-pgvector_0.5.0_arm64.deb
            ├── postgresql-14-pgxman-pgvector_0.5.0_arm64.deb
            └── postgresql-15-pgxman-pgvector_0.5.0_arm64.deb

11 directories, 12 files
```

## Test the extension

<Note>We plan on making it easier to test extensions in the near future.</Note>

Our recommendation is to test the built extension using Docker. You could use a
Dockerfile to build an image, or run the commands manually from inside of the
container.

Below is an example Dockerfile. In order to use this, you'll need your built
extension in `out/` and a `pgxman.yaml` file specifying the package from `out/`
to install.

```Dockerfile theme={null}
FROM postgres:15-bookworm

RUN apt-get update && \
  apt-get install -y curl && \
  curl -sfL https://install.pgx.sh | sh -

COPY out/ /pgxman/out/
COPY pgxman.yaml /pgxman/pgxman.yaml

WORKDIR /pgxman
RUN pgxman install --debug -f pgxman.yaml
```

Here's an example `pgxman.yaml` file for this setup:

```yaml theme={null}
apiVersion: v1
extensions:
- path: "./out/debian/bookworm/postgresql-15-pgxman-yourpackage_1.2.3_arm64.deb"
postgres:
  version: 15
```

## Adding the extension to pgxman

Send a PR to [pgxman/buildkit](https://github.com/pgxman/buildkit), adding your
buildkit to the `buildkit` folder.