Database Schema & Migrations
Relevant source files
The following files were used as context for generating this wiki page:
The database system in Daytona is built on PostgreSQL and managed via TypeORM. It utilizes an Expand and Contract pattern to facilitate zero-downtime deployments, ensuring that database schema changes do not break active API instances during rolling updates. The schema covers core entities including Users, Organizations, Workspaces (Sandboxes), and Infrastructure Nodes.
Sources: apps/api/src/migrations/README.md:1-12, docker/README.md:16-17
Migration Architecture
Daytona employs a structured migration strategy to maintain compatibility between the database and the API. Migrations are categorized based on their impact on the running application.
Expand and Contract Pattern
To support zero-downtime, database changes are split into two distinct phases:
- Pre-deploy (Expand): Additive changes (e.g., adding nullable columns) that are backwards compatible with the current API version.
- Post-deploy (Contract): Breaking changes (e.g., dropping columns) that are executed only after the new API version is fully healthy.
Sources: apps/api/src/migrations/README.md:5-15
Deployment Workflow
The following diagram illustrates the lifecycle of a schema change using the expand/contract pattern.
The workflow ensures that the database always supports the currently running code. For complex changes like renaming a field, database triggers are used during the transition to keep columns synchronized.
Sources: apps/api/src/migrations/README.md:54-85
Core Data Schema
The database schema is defined through TypeORM migrations that establish tables, enums, and relationships.
Entity Relationships
The following ER diagram represents the core relationships between organizations, users, and sandboxes (workspaces).
Primary Tables & Fields
| Table | Key Fields | Description |
|---|---|---|
organization | id, name, personal, total_cpu_quota | Manages resource quotas and ownership boundaries. |
user | id, name, keyPair, publicKeys | Stores user identity and SSH credentials. |
workspace | id, name, state, cpu, mem, disk | Represents a sandbox environment and its resource allocation. |
node | id, domain, cpu, memory, state | Tracks physical or virtual infrastructure instances hosting sandboxes. |
api_key | userId, name, value, organizationId | Authenticates programmatic access to the API. |
Sources: apps/api/src/migrations/1741088883000-migration.ts:13-30, apps/api/src/migrations/1741087887225-migration.ts:13-55
Infrastructure and Resource Management
The schema includes specialized tables for managing the lifecycle of container images and hardware nodes.
Node Management
Nodes are the compute resources where sandboxes are scheduled. They transition through various states tracked in the node_state_enum: initializing, ready, disabled, decommissioned, and unresponsive.
Sources: apps/api/src/migrations/1741087887225-migration.ts:25-33
Workspace (Sandbox) States
Sandboxes utilize a complex state machine to handle creation, execution, and archiving.
Resource Quotas and Constraints
Resource allocation is managed at the Organization level. The migration 1741088883000 transitioned quotas from individual users to organizations to support multi-tenant team structures.
- CPU Quota:
total_cpu_quota(Default 10) - Memory Quota:
total_memory_quota(Default 40) - Disk Quota:
total_disk_quota(Default 100) - Concurrency:
max_concurrent_workspaces(Default 10)
Sources: apps/api/src/migrations/1741088883000-migration.ts:13-20, apps/dashboard/src/components/Sandbox/CreateSandboxSheet.tsx:103-108
Migration Scripts
Developers interact with the migration system through npm scripts:
| Command | Action | Usage Scenario |
|---|---|---|
npm run migration:generate | Generates new migration files | After modifying TypeORM entities. |
npm run migration:run:init | Runs all pending migrations | Initial setup or development. |
npm run migration:run:pre-deploy | Runs pre-deploy/ migrations | Before deploying a new API version. |
npm run migration:run:post-deploy | Runs post-deploy/ migrations | After a new API version is healthy. |
npm run migration:revert | Reverts the last executed migration | Undoing changes during development. |
Sources: apps/api/src/migrations/README.md:88-115
Summary
The Database Schema & Migrations system provides a resilient foundation for Daytona's infrastructure. By utilizing the expand and contract pattern and segregating migrations into pre-deploy and post-deploy phases, the project ensures high availability. The schema tightly integrates resource management, organization-based access control, and automated sandbox lifecycle tracking.