Database Schema & State Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Database Schema & State Management system in Harbor Next provides the persistence layer for managing core entities such as users, projects, repositories, and artifacts. It ensures that system state—ranging from role-based access control (RBAC) configurations to vulnerability scan results and replication policies—is consistently stored and accessible across different service components.
The system utilizes a relational database (PostgreSQL) as the primary backend for "DB mode" operations, where user identities and project memberships are managed locally. This architectural foundation supports complex features like garbage collection (GC), tag retention policies, and cross-registry replication by tracking the lifecycle and relationship of OCI artifacts.
Sources: api/v2.0/swagger.yaml, tests/testcases/Group3-RBAC/3-11-DB-admin-user-manage-project-members.md:1-10
Entity Relationships and Schema Design
Harbor Next organizes data around a hierarchical structure where users belong to projects, and projects contain repositories which house artifacts. This structure is enforced through foreign key relationships and unique constraints in the underlying schema.
Core Data Hierarchy
The following ER diagram illustrates the primary relationships between the core entities managed within the database:
The diagram shows how users and groups are linked to projects via project members, and the containment hierarchy of repositories and artifacts.
Sources: api/v2.0/swagger.yaml:1380-1500, src/testing/suite.go:148-180
Key Data Models
The system defines several critical models for representing state:
| Model | Primary Fields | Purpose |
|---|---|---|
| Project | project_id, owner_id, name, metadata | Defines the top-level isolation unit for RBAC and storage. |
| Artifact | id, type, digest, size, repository_id | Represents an OCI artifact (image, chart, etc.). |
| User | user_id, username, email, sysadmin_flag | Stores local user credentials and system-wide privileges. |
| Member | id, project_id, entity_id, role_id | Maps users/groups to specific project-level roles. |
| Tag | id, repository_id, artifact_id, name | Provides human-readable identifiers for specific artifact digests. |
Sources: api/v2.0/swagger.yaml:1380-1600
State Management and Persistence Logic
State management is handled through a combination of CRUD operations via the REST API and internal transaction logic within the Go backend.
Project & Member Lifecycle
When a project is created, the system must initialize metadata and assign the creator as the initial Project Admin.
This sequence ensures that a project cannot exist without at least one administrative member assigned.
Sources: src/testing/suite.go:148-183, api/v2.0/swagger.yaml:1662-1675
Soft Deletion
Harbor Next implements soft deletion for projects. Instead of purging records immediately, the system updates a deleted flag and renames the entity to prevent name collisions during subsequent creations.
- SQL Logic:
UPDATE project SET deleted = true, name = <name>#<id> WHERE project_id = ?
Sources: src/testing/suite.go:186-197
Role-Based Access Control (RBAC) State
The system maintains role assignments that dictate what actions a user can perform on specific resources. Roles are stored as integers mapping to specific permission sets.
Standard Roles
- Project Admin (1): Full control over projects, including member management.
- Maintainer (4): Can manage repositories and artifacts but not project settings.
- Developer (2): Can push and pull images.
- Guest (3): Read-only access (pull).
- Limited Guest (5): Restricted read access.
Sources: api/v2.0/swagger.yaml:2150-2160, tests/testcases/Group3-RBAC/3-01-DB-user-manage-project-members.md:20-25
Permission Mapping Table
| Resource | Action | Role (Min. Required) |
|---|---|---|
repository | push | Developer |
repository | pull | Guest |
project | delete | Project Admin |
member | create | Project Admin |
Sources: api/v2.0/swagger.yaml:2050-2070, tests/testcases/Group3-RBAC/3-11-DB-admin-user-manage-project-members.md
Database Testing & Suite Management
For development and CI, the project provides a testing suite that manages database state, ensuring a clean environment for each test case.
- SetupSuite: Initializes the configuration and prepares the PostgreSQL connection.
- TearDownSuite: Executes custom SQL (
ClearSQLs) and cleans specific tables (ClearTables) to reset state. - ORM Integration: Uses
beego/ormfor executing raw SQL and handling object-relational mapping.
Sources: src/testing/suite.go:37-67
Conclusion
Database Schema & State Management in Harbor Next is a centralized system that tracks the entire lifecycle of OCI artifacts and the users interacting with them. By using a strictly defined relational schema and transaction-backed persistence logic, the system ensures data integrity for critical operations like image pushes, role assignments, and system-wide garbage collection.