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

# PostgreSQL

> Run PostgreSQL on an Archil disk for elastic, S3-backed storage

[PostgreSQL](https://www.postgresql.org/) is an open-source relational database management system (RDBMS) that's
popular for its reliability, feature set, and community support.

This guide walks you through running PostgreSQL on an Archil disk. PostgreSQL doesn't need to know
anything about Archil or S3 -- it just reads and writes files to its data directory as usual. By pointing
that data directory at an Archil mount, you get:

* **Elastic storage**: no need to provision or resize disks as your database grows
* **S3 durability**: all data is automatically synchronized to S3 in the background
* **Pay for what you use**: you're only billed for active data, not provisioned capacity
* **Portability**: unmount from one server and mount on another to move your database

## Create an Archil disk

First, follow the Archil [Getting Started Guide](/getting-started/quickstart) to create an Archil disk.

## Install PostgreSQL

The exact instructions for installing PostgreSQL will vary depending on your operating system. For example, on Amazon Linux 2023,
you can install PostgreSQL with the following command:

```bash theme={null}
sudo dnf update -y
sudo dnf install -y postgresql15 postgresql15-server
```

Next, mount your Archil disk to an easy to access directory.

```bash theme={null}
# Mount Archil disk
sudo mkdir -p /mnt/archil
export ARCHIL_MOUNT_TOKEN="<token>"
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount <disk-name> /mnt/archil --region aws-us-east-1

# Create the directory for PostgreSQL data
sudo mkdir -p /mnt/archil/pgdata
sudo chown -R postgres:postgres /mnt/archil/pgdata
```

Then, edit the PostgreSQL service files to point to the Archil disk. On Amazon Linux 2023, we do this with the `systemctl` command

```bash theme={null}
sudo systemctl edit postgresql
```

Add the following lines to the file:

```bash theme={null}
[Service]
Environment=PGDATA=/mnt/archil/pgdata
```

Then, initialize the PostgreSQL database, and start the service.

```bash theme={null}
sudo postgresql-setup --initdb
sudo systemctl start postgresql
```

You can validate that postgres is successfully running on Archil by executing the following command:

```bash theme={null}
sudo -u postgres psql -c 'SHOW data_directory;'
```

This should output the PGDATA directory that we previously set up, `/mnt/archil/pgdata`.

## Connect and use your database

Now that PostgreSQL is running on Archil, you can connect to it and use it normally with the `psql` command or from
an application. PostgreSQL is unaware of Archil -- it reads and writes files to its data directory like it normally
would. Archil handles caching those files on fast SSD storage and asynchronously synchronizing them to S3.

When your database is idle, you're not charged for Archil's high-speed cache -- you only pay for the data stored in S3.

## (Optional) Run pgbench benchmarks to validate performance

First, install the `pgbench` tool.

```bash theme={null}
sudo dnf install -y postgresql15-contrib
```

Then, initialize the benchmark database:

```bash theme={null}
sudo -u postgres createdb benchdb
sudo -u postgres pgbench -i -s 10 benchdb
```

Finally, you can run a basic benchmark to validate performance.

```bash theme={null}
sudo -u postgres pgbench -c 10 -j 2 -T 30 benchdb
```

This will run a benchmark for 30 seconds with 10 connections and 2 threads.