mem0ai--mem0/docs/migration/server-pgvector-upgrade.mdx

---
title: "Server: Upgrading the pgvector Docker Image"
description: "Migrate your self-hosted Mem0 server from the archived ankane/pgvector image to the official pgvector/pgvector image."
icon: "arrow-right"
iconType: "solid"
---

## Overview

The self-hosted Mem0 server has upgraded its PostgreSQL Docker image:

| | Before | After |
| --- | --- | --- |
| Docker image | `ankane/pgvector:v0.5.1` | `pgvector/pgvector:pg17` |
| PostgreSQL | 15 | 17 |
| pgvector | 0.5.1 | 0.8.0 |
| Credentials | Hardcoded `postgres` / `postgres` | Set via `POSTGRES_USER` / `POSTGRES_PASSWORD` env vars |

<Warning>
The `ankane/pgvector` image is **archived and no longer maintained**. The new `pgvector/pgvector` image is the official distribution maintained by the pgvector project.
</Warning>

<Info>
**Should you migrate?**
- You are running the Mem0 server via `docker-compose.yaml` in the `server/` directory.
- You want to stay on a maintained, actively-patched PostgreSQL + pgvector image.
- You want pgvector 0.8.0 features (improved HNSW performance, parallel index builds).
</Info>

## Fresh Installs

No migration is needed. Copy the example env file, set your password, and start the stack:

```bash
cd server
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD (required) and OPENAI_API_KEY at minimum
make up
```

## Migrating an Existing Install

PostgreSQL 17 cannot read data files created by PostgreSQL 15 directly. You need to export your data from the old container and import it into the new one.

### 1. Back Up Your Data

With the **old** stack still running:

```bash
cd server
docker compose exec -T postgres pg_dumpall -U postgres > mem0_backup.sql
```

Verify the dump is non-empty:

```bash
ls -lh mem0_backup.sql
```

<Warning>
Do not skip this step. The next step permanently deletes your Postgres data volume.
</Warning>

### 2. Stop the Old Stack and Remove the Volume

```bash
docker compose down
docker compose down -v
```

### 3. Update Your `.env`

Postgres credentials are no longer hardcoded in `docker-compose.yaml`. Add them to your `.env`:

```bash
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<your-password>    # required: compose will refuse to start without it
POSTGRES_COLLECTION_NAME=memories
```

<Info>
`POSTGRES_PASSWORD` is **required**: `docker compose up` will refuse to start without it. If you previously relied on the hardcoded default, set `POSTGRES_PASSWORD=postgres`.
</Info>

### 4. Start Only Postgres

Start **only** the Postgres container first: do **not** start the mem0 API yet.
The API runs `alembic upgrade head` on startup, which creates empty tables that
would conflict with the restore.

```bash
docker compose up -d postgres
```

Wait for Postgres to become healthy:

```bash
docker compose exec -T postgres pg_isready -q && echo "ready" || echo "not ready"
```

### 5. Restore Your Data

```bash
docker compose exec -T postgres psql -U postgres < mem0_backup.sql
```

You may see notices like `role "postgres" already exists`: these are safe to ignore.

<Warning>
You must restore **before** starting the mem0 API container. The API runs
database migrations on startup which create empty tables: restoring after
that would fail with duplicate-key errors and lose your API keys and settings.
</Warning>

### 6. Start the API

Now start the mem0 API container. Alembic will detect the existing tables and
only apply any new migrations:

```bash
docker compose up -d mem0
```

### 7. Verify

```bash
# Check service health
cd server && make health

# Confirm memories are accessible
curl -s http://localhost:8888/memories?user_id=<your-user-id> \
  -H "X-API-Key: <your-api-key>"
```

## Rollback

If something goes wrong, revert the image tag in `docker-compose.yaml`:

```yaml
postgres:
    image: ankane/pgvector:v0.5.1
```

Then destroy the new volume, start the old image, and restore from your backup:

```bash
docker compose down -v
docker compose up -d --build
docker compose exec -T postgres psql -U postgres < mem0_backup.sql
```

## Need Help?

- Join our [Discord community](https://mem0.ai/discord) for real-time support
- Open an issue on [GitHub](https://github.com/mem0ai/mem0/issues)