Data Layer

Relevant source files

• docs/docs/administration/postgres-standalone.md
• docs/docs/install/environment-variables.md
• mobile/openapi/lib/api/search_api.dart
• mobile/openapi/lib/model/metadata_search_dto.dart
• mobile/openapi/lib/model/random_search_dto.dart
• mobile/openapi/lib/model/smart_search_dto.dart
• mobile/openapi/lib/model/statistics_search_dto.dart
• server/src/app.module.ts
• server/src/bin/sync-sql.ts
• server/src/constants.ts
• server/src/controllers/search.controller.ts
• server/src/dtos/env.dto.ts
• server/src/dtos/search.dto.ts
• server/src/main.ts
• server/src/middleware/file-upload.interceptor.ts
• server/src/queries/map.repository.sql
• server/src/queries/search.repository.sql
• server/src/repositories/config.repository.spec.ts
• server/src/repositories/config.repository.ts
• server/src/repositories/database.repository.ts
• server/src/repositories/map.repository.ts
• server/src/repositories/search.repository.ts
• server/src/repositories/storage.repository.spec.ts
• server/src/repositories/storage.repository.ts
• server/src/schema/migrations/1744910873969-InitialMigration.ts
• server/src/schema/migrations/1776792304485-ReconcileSqlToolsUpgradeChanges.ts
• server/src/services/database.service.spec.ts
• server/src/services/database.service.ts
• server/src/services/search.service.spec.ts
• server/src/services/search.service.ts
• server/src/utils/database.ts
• server/src/workers/api.ts
• server/src/workers/microservices.ts
• server/test/medium/globalSetup.ts
• server/test/repositories/config.repository.mock.ts
• server/test/repositories/storage.repository.mock.ts
• server/tsconfig.build.json
• server/tsconfig.json

The Data Layer encompasses all persistent storage mechanisms in Immich, including the PostgreSQL database with vector extensions, Redis for caching and job queuing, and the file system for storing media assets and their derivatives.

---

Overview

Immich's data layer consists of three primary storage systems that work together to provide efficient asset management, search capabilities, and background processing:

1. PostgreSQL with Vector Extensions - Primary relational database using Kysely as the query builder server/src/repositories/search.repository.ts2 It utilizes specialized extensions for vector similarity search server/src/constants.ts22-27
2. Redis/Valkey - In-memory data store for caching and managing asynchronous background tasks via BullMQ server/src/repositories/config.repository.ts52-55
3. File Storage - Hierarchical file system for original assets, thumbnails, and encoded videos, managed by the StorageRepository server/src/app.module.ts30

Data Layer Architecture

The following diagram bridges the high-level storage concepts with the specific code entities that manage them.

Diagram: Data Layer Entity Mapping

Sources: server/src/repositories/search.repository.ts181-182 server/src/repositories/database.repository.ts55-65 server/src/app.module.ts23-40

---

PostgreSQL Database

Immich requires PostgreSQL (version >=14.0.0) server/src/constants.ts15 It is the source of truth for all metadata, user configurations, and asset relationships.

Vector Extensions

To power "Smart Search" (semantic search) and face recognition, Immich leverages vector similarity search. It supports two primary extensions:

• VectorChord (vchord): The preferred extension for high performance and quality docs/docs/administration/postgres-standalone.md79-81
• pgvector (vector): Required as a prerequisite for VectorChord to provide the base vector data types docs/docs/administration/postgres-standalone.md13-15

The DatabaseRepository manages these extensions, including creation, version checks, and reindexing server/src/repositories/database.repository.ts109-157

Extension	Code Identifier	Version Range
pgvector	DatabaseExtension.Vector	>=0.5 <1
VectorChord	DatabaseExtension.VectorChord	>=0.3 <2

Sources: server/src/constants.ts15-27 server/src/repositories/database.repository.ts75-97

Core Schema and Search

Immich uses Kysely to interact with the database schema defined in DB server/src/schema/index.ts Key search operations are centralized in SearchRepository, which builds complex queries for metadata, random assets, and large files server/src/repositories/search.repository.ts181-265

Vector Search Implementation

Smart search utilizes the <=> operator for cosine distance in SQL server/src/queries/search.repository.sql93

Sources: server/src/repositories/search.repository.ts196-206 server/src/queries/search.repository.sql75-98 server/src/repositories/database.repository.ts50-53

---

Redis Cache and Queue

Redis is essential for managing the asynchronous nature of photo processing.

Configuration and Connection

The ConfigRepository parses Redis connection details from environment variables server/src/repositories/config.repository.ts102 It supports standard host/port configurations or a full REDIS_URL docs/docs/install/environment-variables.md70-75

BullMQ Queuing

Background jobs are managed via BullModule server/src/app.module.ts64

• Queues: Defined in QueueName (e.g., thumbnail-generation, metadata-extraction) server/src/enum.ts
• Workers: The system can be configured to run specific workers using IMMICH_WORKERS_INCLUDE or IMMICH_WORKERS_EXCLUDE docs/docs/install/environment-variables.md61-62

Sources: server/src/repositories/config.repository.ts52-55 server/src/app.module.ts64-65

---

File Storage Architecture

Immich stores assets on the host file system, mapped into the container.

Storage Locations

• Upload Location: Defined by UPLOAD_LOCATION on the host, mapped to /data inside the container docs/docs/install/environment-variables.md23-38
• Internal Paths: The server expects a specific structure within the media location for library files, thumbnails, and encoded videos server/src/repositories/config.repository.ts114-117

Geodata and Reverse Geocoding

The data layer also includes a specialized MapRepository that manages offline reverse geocoding using cities500.txt and Natural Earth data server/src/repositories/map.repository.ts8-70

Geocoding Flow:

1. City Lookup: Uses earth_distance and earth_box on the geodata_places table server/src/repositories/map.repository.ts150-162
2. Boundary Fallback: If no city is found within 25km, it checks naturalearth_countries using point-in-polygon logic server/src/repositories/map.repository.ts174-183

Sources: server/src/repositories/map.repository.ts42-201 server/src/constants.ts50-51

---

Data Layer Environment Variables

The behavior of the data layer is heavily influenced by environment variables defined in EnvSchema server/src/repositories/config.repository.ts174

Variable	Description	Default
DB_URL	Full Postgres connection string	N/A
REDIS_HOSTNAME	Redis server address	immich_redis
UPLOAD_LOCATION	Root path for all media	N/A
IMMICH_MEDIA_LOCATION	Internal container path for data	/data
IMMICH_PROCESS_INVALID_IMAGES	Attempt thumbnailing for corrupt files	false

Sources: docs/docs/install/environment-variables.md20-48 server/src/dtos/env.dto.ts