Local Postgres container names collide across projects

Open
  • Is something wrong?
#1,160 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
docker, postgresql, rust
Domain
cli, databases

Research direction

Start in crates/clickhousectl/src/local/docker.rs with pg_container_name, then trace how ensure_name_free and inspect, stop, and remove identify containers and use project labels. Check the corresponding tests and existing ClickHouse server naming for project-scoped behavior. Done means names are project-specific and existing containers with old names can still be managed by their project.

Written by the indexing model from the issue text.

Description

bug local

Problem

Local Postgres instances are project-scoped. Data lives under <project>/.clickhouse/servers/<name>-pg<major>/, and containers carry a project label. But the Docker container name has no project component:

// crates/clickhousectl/src/local/docker.rs
pub fn pg_container_name(user_name: &str, major: &str) -> String {
    format!("clickhousectl-pg-{}-{}", user_name, major)
}

ensure_name_free returns ContainerNameConflict when an existing container with that name has a different project label. So two projects can't both run local postgres start with the default name and the same major version: the second one fails.

This hits the common parallel-agent setup hardest. Several coding agents, each in its own git worktree of one repo, each run local postgres start and expect isolated instances.

Expected

Instance names are unique per project, as they are for ClickHouse servers, so the container name should be too. For example, clickhousectl-pg-<project hash>-<name>-<major>, where the hash is a short stable hash of the canonical project root.

Notes

  • Migration: existing containers keep their old names until they are next recreated. Inspect, stop and remove should accept both forms and match on the project label.
  • Docker limits container names to [a-zA-Z0-9][a-zA-Z0-9_.-]. Keep the hash short so the name stays readable in docker ps.
  • Related: a cross-project port race is possible. Port probing is serialised only by the per-project metadata lock, so two projects starting at the same moment could pick the same port. That is inferred from the code, not reproduced.
  • Found while researching a global registry for local servers.

🤖 Generated with Claude Code

Dominant language
Rust
Stars
80
Forks
9
Avg merge
3d 20h
Merged PRs (30d)
57

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ClickHouse/clickhousectl

All issues in ClickHouse/clickhousectl

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.