# What Database Does Pentagi Use and How Is It Managed?

> Discover Pentagi's database setup: PostgreSQL with pgvector for vector embeddings. Learn how connections and schema changes are managed using DATABASE_URL and Goose migrations.

- Repository: [VXControl/pentagi](https://github.com/vxcontrol/pentagi)
- Tags: internals
- Published: 2026-03-21

---

**Pentagi uses PostgreSQL with the optional pgvector extension for vector embeddings, managing connections through the `DATABASE_URL` environment variable and schema changes via Goose migrations on top of GORM.**

The **vxcontrol/pentagi** repository implements a robust **Pentagi database** layer built entirely on PostgreSQL to persist agent states, conversation histories, and AI vector data. The architecture follows a three-tier initialization approach that combines raw SQL connections, ORM abstractions, and version-controlled migrations to ensure reliable data operations across development and production deployments.

## Pentagi Database Technology Stack

Pentagi stores all persistent data in **PostgreSQL**, leveraging the optional **pgvector** extension when available to store and query vector embeddings for AI-powered analysis features. This choice provides ACID compliance, complex query support, and vector similarity search capabilities required by the platform's security automation workflows.

## Pentagi Database Configuration

Database connectivity is controlled entirely through the **`DATABASE_URL`** environment variable. In [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go), the system defines a sensible default that points to a local pgvector service:

```

postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable

```

If the environment variable is omitted, Pentagi falls back to this default, making local development with Docker Compose seamless while allowing production deployments to override the connection string with secure credentials.

## Pentagi Database Initialization Architecture

When the server starts in [`backend/cmd/pentagi/main.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/pentagi/main.go), it establishes the database stack through three coordinated layers that run sequentially.

### Raw SQL Connection Layer

The application first opens a raw connection using the standard `database/sql` driver with the PostgreSQL dialect:

```go
db, err := sql.Open("postgres", cfg.DatabaseURL)

```

This operation occurs at line 72 of [`backend/cmd/pentagi/main.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/pentagi/main.go), creating the foundational connection pool that both the ORM and migration tools will utilize.

### GORM ORM Abstraction

Next, the system initializes **GORM** (the Go ORM) to provide high-level model interactions and automatic struct mapping:

```go
orm, err := database.NewGorm(cfg.DatabaseURL, "postgres")

```

This call at line 83 invokes the wrapper implementation in [`backend/pkg/database/gorm.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/database/gorm.go), establishing an abstraction layer over the raw SQL connection for application business logic.

### Goose Migration Management

Finally, Pentagi ensures schema consistency by running database migrations through **Goose**, configured explicitly for the PostgreSQL dialect:

```go
if err := goose.SetDialect("postgres"); err != nil {
    log.Fatalf("goose dialect error: %v", err)
}
if err := goose.Up(db); err != nil {
    log.Fatalf("migration failed: %v", err)
}

```

These calls around line 90 of [`backend/cmd/pentagi/main.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/pentagi/main.go) apply any pending schema changes from the migration files, ensuring the database structure matches the application code before accepting requests.

## Schema Version Control

All database schema definitions are version-controlled as SQL files in the **`backend/migrations/sql/`** directory. Goose processes these files in lexical order (typically prefixed with timestamps) when `goose.Up(db)` executes. For example, [`20241026_115120_initial_state.sql`](https://github.com/vxcontrol/pentagi/blob/main/20241026_115120_initial_state.sql) contains the foundational DDL statements for tables, indices, and constraints that define the initial Pentagi schema.

Additionally, type-safe SQL queries are generated in `backend/pkg/database/sqlc/*.go` files, providing compiled-time checked database operations that complement the GORM models.

## Summary

- **Pentagi** uses **PostgreSQL** (optionally with the **pgvector** extension) as its sole persistent data store
- Connection parameters are configured via the **`DATABASE_URL`** environment variable with defaults defined in [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go)
- The database stack initializes through three layers: **raw SQL connections** (`sql.Open`), **GORM ORM** (`database.NewGorm`), and **Goose migrations** (`goose.Up`)
- Schema changes are version-controlled in **`backend/migrations/sql/`** and applied automatically on server startup

## Frequently Asked Questions

### Can Pentagi use a database other than PostgreSQL?

No. The codebase hardcodes the `"postgres"` driver dialect in the `sql.Open()` call at line 72 of [`backend/cmd/pentagi/main.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/pentagi/main.go) and explicitly sets the Goose dialect to `"postgres"` at line 90. Additionally, the optional **pgvector** extension provides vector storage capabilities specific to PostgreSQL that support Pentagi's AI embedding features.

### What is the default database connection string for Pentagi?

If the `DATABASE_URL` environment variable is not set, Pentagi defaults to `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` as implemented in [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go). This default assumes a PostgreSQL service named `pgvector` is accessible on the default port with the specified credentials.

### How does Pentagi handle database schema migrations?

Pentagi uses **Goose** for migration management. During startup, the application executes `goose.SetDialect("postgres")` followed by `goose.Up(db)` to apply any pending SQL migrations from the `backend/migrations/sql/` directory. This ensures the database schema remains synchronized with the application version without manual intervention.

### Where are the database models and SQL queries defined in the codebase?

High-level data models interact through **GORM** configured in [`backend/pkg/database/gorm.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/database/gorm.go), while type-safe SQL query helpers are generated in `backend/pkg/database/sqlc/*.go` files. Raw schema definitions, including table structures and constraints, reside as version-controlled `.sql` files under `backend/migrations/sql/`.