What Database Does Harbor Use and What Is It Used For?

Harbor uses PostgreSQL as its default persistence layer to store all core operational metadata, including user authentication data, project and artifact information, vulnerability scan results, and system configuration.

The goharbor/harbor container registry relies on PostgreSQL as its primary relational database for storing every aspect of its operational state. According to the source code in src/lib/config/metadata/metadatalist.go, the system-wide configuration sets DATABASE_TYPE to "postgresql" by default. Understanding what database Harbor uses and how it configures the connection is essential for administrators deploying production instances.

PostgreSQL as Harbor's Default Database

Harbor explicitly defaults to PostgreSQL as defined in the metadata configuration list. In src/lib/config/metadata/metadatalist.go lines 79-80, the DATABASE_TYPE parameter is initialized to "postgresql", establishing it as the standard persistence mechanism.

The concrete implementation resides in src/common/dao/pgsql.go, which registers the pgx driver and constructs the connection string for PostgreSQL instances. This file handles database registration, connection pooling, and schema migration logic. The Database model defined in src/common/models/database.go contains a PostGreSQL field that encapsulates connection details including host, port, database name, and SSL mode.

What Harbor Stores in PostgreSQL

Harbor stores all core metadata in PostgreSQL, spanning user management, registry operations, security scanning, and system auditing.

User and Authentication Data

PostgreSQL maintains user accounts, group memberships, and authentication integration data for LDAP and OIDC providers. The core service queries these tables during login workflows and permission validations.

Project and Artifact Metadata

All project definitions, repository configurations, and artifact metadata reside in PostgreSQL tables. The Registry API and Harbor UI retrieve this data to display repository contents and handle push/pull operations.

Vulnerability Scan Results

Security scanning integration with Trivy stores vulnerability reports and scan execution statuses in the database. This enables Harbor to display security summaries and enforce vulnerability-based admission policies.

Jobservice and Audit Logs

The Jobservice component persists job definitions, execution logs, and system audit records to PostgreSQL. This includes scheduled tasks, garbage collection logs, and replication operations.

Database Configuration Implementation

Harbor loads and manages PostgreSQL configuration through several specialized components that handle runtime configuration and persistence.

Loading Configuration at Runtime

The src/lib/config/systemconfig.go file implements the runtime configuration loader. The Database() function reads PostgreSQL settings from the configuration manager and returns a *models.Database struct populated with connection parameters.

// Get the complete DB config (type + PostgreSQL details)
cfg, err := config.Database()
if err != nil {
    log.Fatalf("failed to load DB config: %v", err)
}
pg := cfg.PostGreSQL
fmt.Printf("Connecting to PostgreSQL %s:%d/%s (sslmode=%s)\n",
    pg.Host, pg.Port, pg.Database, pg.SSLMode)

Source: src/lib/config/systemconfig.go lines 54-71

Registering the PostgreSQL Driver

The data access layer initializes the PostgreSQL driver in src/common/dao/pgsql.go. The New() function creates a DAO instance and registers the pgx driver with the connection pool.

// Create a PostgreSQL DAO instance
pgDAO := dao.New()
err := pgDAO.Register() // internally calls pgsql.NewPGSQL and Register()
if err != nil {
    log.Fatalf("failed to register PostgreSQL DAO: %v", err)
}

Source: src/common/dao/pgsql.go lines 62-78

Persisting Configuration Values

Harbor persists system configuration changes to PostgreSQL using the database-backed configuration store. The src/pkg/config/db/manager.go implements the ConfigStore interface for saving key-value pairs to the database.

cfgMgr := config.NewManager()
dbStore := config.NewConfigStore(&config.Database{cfgDAO: dao.New()})
err = dbStore.Save(context.Background(), map[string]any{
    common.AUTHMode: "db_auth",
})
if err != nil {
    log.Fatalf("save config error: %v", err)
}

Source: src/pkg/config/db/manager.go lines 30-38

Summary

• Harbor defaults to PostgreSQL as configured in src/lib/config/metadata/metadatalist.go.
• The pgx driver implementation in src/common/dao/pgsql.go handles connection management and schema migrations.
• PostgreSQL stores users, groups, projects, artifacts, vulnerability scans, jobs, and audit logs.
• Runtime configuration loads from src/lib/config/systemconfig.go, which returns a PostGreSQL struct containing connection details.
• System configuration values persist to the database via src/pkg/config/db/manager.go.

Frequently Asked Questions

Does Harbor support databases other than PostgreSQL?

While earlier versions of Harbor supported MySQL, the current goharbor/harbor source code defaults exclusively to PostgreSQL. The DATABASE_TYPE configuration in src/lib/config/metadata/metadatalist.go defaults to "postgresql", and the DAO layer specifically implements pgx driver support. Other database engines like MySQL or SQLite appear only in legacy documentation or test files, not in production code paths.

How does Harbor handle database connection strings?

Harbor constructs PostgreSQL connection strings in src/common/dao/pgsql.go using the PostGreSQL model fields defined in src/common/models/database.go. The implementation builds a connection string that includes host, port, database name, username, password, and SSL mode parameters, then registers this with the pgx driver for connection pooling.

Where is the database type configured in Harbor?

The database type is configured in src/lib/config/metadata/metadatalist.go, where DATABASE_TYPE defaults to "postgresql". At runtime, src/lib/config/systemconfig.go loads these settings and returns the database configuration through the Database() function, which provides the PostGreSQL connection details to the rest of the application.

What PostgreSQL driver does Harbor use?

Harbor uses the pgx driver for PostgreSQL connectivity. The driver registration and connection management occur in src/common/dao/pgsql.go, which imports the pgx library and implements the DAO interface for PostgreSQL-specific operations including connection pooling and database health checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}