Database URL Rewriting
Relevant source files
The following files were used as context for generating this wiki page:
Database URL Rewriting is a core feature of Docktree that enables multi-tenancy within a shared platform tier. When a developer uses git worktrees, Docktree ensures that each worktree's services remain isolated even when connecting to shared database services (such as PostgreSQL, MySQL, or MongoDB). This is achieved by dynamically modifying the connection strings in the environment variables of consumer services during the up process.
The system identifies connection strings (e.g., DATABASE_URL) and replaces the default database name with a unique "tenant" database name specific to the current worktree. This allows multiple worktrees to share a single database container instance while maintaining data isolation through separate logical databases.
Sources: internal/compose/urlrewrite_test.go:1-5, internal/cli/up.go:121-150, internal/compose/platform.go:214-235
Architecture and Data Flow
The rewriting process occurs during the synthesis of the worktree's Docker Compose project. When docktree up is executed, the CLI identifies shared services configured with per_database tenancy and prepares a synthesized Compose file where environment variables are injected or modified.
Rewriting Logic Flow
The following diagram illustrates the flow from detecting shared services to writing the modified Compose project:
The system resolves a "Tenant Name" using the repository slug, instance name, and logical database name before passing it to the rewriting utility.
Sources: internal/cli/up.go:110-165, internal/compose/platform.go:214-250
Key Components and Functions
URL Modification Logic
The primary logic for parsing and rebuilding connection strings resides in the rewriting module. It supports a wide variety of URL schemes and formats, including standard PostgreSQL, MongoDB SRV, JDBC prefixes, and SQLAlchemy dialects.
| Function | Description |
|---|---|
RewriteURL | Takes a raw connection string and a tenant name, returning a string where the path/database component is replaced by the tenant name. |
RewriteURLEnvs | Iterates through a map of environment variables and applies RewriteURL to those explicitly listed in the configuration. |
SynthesizeWorktree | The high-level orchestrator that deep-copies the project environment and coordinates the rewriting of both URLs and raw database name variables. |
Sources: internal/compose/urlrewrite_test.go:11-93, internal/compose/platform.go:161-260
Database Name Injection
In addition to full URL rewriting, Docktree supports db_name_envs. This is used when a service constructs its connection URL at runtime (e.g., via a shell script or secrets wrapper) and only needs the raw database name injected into a specific variable like POSTGRES_DB.
Configuration and Tenancy Modes
Rewriting behavior is governed by the shared.services section in docktree.yml. Services must be configured with specific tenancy models to trigger the rewriting engine.
Tenancy Options
The kind of service dictates which tenancy modes are valid.
- full_share: The service is shared globally; no rewriting occurs.
- per_database: Triggers the creation of unique logical databases and rewriting of environment variables.
| Kind | Supported Tenancy | Default Tenant Env |
|---|---|---|
postgres | per_database, full_share | DOCKTREE_DB |
mysql | per_database, full_share | DOCKTREE_DB |
mongodb | per_database, full_share | DOCKTREE_DB |
redis | full_share | REDIS_KEY_PREFIX |
Sources: internal/config/config.go:168-185, internal/cli/init.go:300-310
Implementation Example (Configuration)
The following snippet demonstrates how url_envs are defined to target specific variables for rewriting:
shared:
services:
db:
kind: postgres
tenancy: per_database
url_envs:
- DATABASE_URL
- REPLICA_URL
db_name_envs:
- POSTGRES_DB
Sources: internal/cli/init.go:245-265, internal/config/config.go:50-60
Implementation Details
Handling Specific URL Formats
The rewriting logic is designed to be robust against complex URL structures. It preserves credentials, query strings (such as Prisma's ?schema=public), and port numbers while only swapping the database path.
// Example of handled transformations from test cases:
// Input: postgres://user:secret@db:5432/myapp?sslmode=require
// Tenant: myrepo_feat_abc
// Output: postgres://user:secret@db:5432/myrepo_feat_abc?sslmode=require
Sources: internal/compose/urlrewrite_test.go:15-45
Synthesis Pipeline
The synthesis pipeline ensures that worktree containers are attached to a docktree-platform-<repo>-net network, allowing them to resolve shared services by their original names (e.g., db) while the environment variables point to isolated logical databases.
Summary
Database URL Rewriting enables Docktree to provide a "Serverless" experience for local databases. By dynamically modifying connection strings and database name variables during the synthesis of the Docker Compose project, Docktree maintains strict data isolation across git worktrees while minimizing the resource overhead of running multiple database containers. The system supports complex URL schemes and integrates with external platform networks to ensure seamless connectivity.