pg_dump: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432"
failed: FATAL: database "flin-postgres" does not existThis error appeared in the logs the first time a user triggered a database backup for a PostgreSQL instance deployed via a template. The backup engine ran pg_dump -U postgres flin-postgres inside the container. The database inside the container was named "0cron" (from the POSTGRES_DB environment variable). The app was named "flin-postgres" (the human-readable label in the dashboard).
The backup engine used the wrong name because it had no way to distinguish the two. This article explains why the distinction matters, how template-deployed databases store their credentials, and the decryption pipeline we built to resolve it.
Two Systems, One Database
sh0 has two ways to run a database:
Formal databases are created through the Database Management API (POST /api/v1/databases). They have a dedicated databases table in SQLite with fields for engine, name, version, container_id, and port. The name field is the actual database name (e.g., "my_app_db"). Backups for formal databases work correctly because db_name maps directly to the PostgreSQL database.
Template-deployed databases are created through the Stack/Template system. A user deploys the "postgres" template, which creates an App record in the apps table. The app has a name (e.g., "flin-postgres"), a stack (e.g., "postgres"), and a container_id. But the actual database name is buried in an environment variable -- POSTGRES_DB -- which was set during template deployment and encrypted with AES-256-GCM before storage.
When the backup engine received source_type: "database" and source_id: <uuid>, it first tried Database::find_by_id(). For template databases, this returned "not found" because the record is in apps, not databases. The fallback then loaded the app and used app.name as db_name.
The app name is a label. The database name is a PostgreSQL identifier. They have nothing to do with each other.
The Credential Storage Chain
Understanding the fix requires understanding how template environment variables flow through the system:
Step 1: Template Definition
The postgres.yaml template defines variables:
yamlvariables:
- name: POSTGRES_PASSWORD
required: true
generated: secret_32
- name: POSTGRES_DB
default: "app"Step 2: Template Deployment
When a user deploys the template, the substitution engine resolves ${POSTGRES_PASSWORD} to a 32-character random secret and ${POSTGRES_DB} to either the user's input or the default "app".
Step 3: Encryption and Storage
The resolved values are encrypted with the master key and stored in the env_vars table:
rustlet value_encrypted = sh0_auth::crypto::encrypt(
&master_key,
value.as_bytes(),
)?;
EnvVar {
id: uuid::Uuid::new_v4().to_string(),
app_id: Some(app_id.to_string()),
key: "POSTGRES_DB".to_string(),
value_encrypted,
// ...
}.insert(&pool)?;Step 4: Container Launch
The Docker container is started with the decrypted values as environment variables. PostgreSQL reads POSTGRES_DB and creates the database at startup. From this point, the container has a running database named whatever POSTGRES_DB was set to -- but the only record of that name is the encrypted env var in SQLite.
The Decryption Pipeline
The fix was to decrypt the env vars at backup time and extract the real database name. The credentials handler (get_db_credentials) already did this for the dashboard's "Database Credentials" card. We extracted the pattern into a reusable function:
rustfn decrypt_env_map(
master_key: &Option<Arc<MasterKey>>,
env_vars: &[EnvVar],
) -> HashMap<String, String> {
let mut map = HashMap::new();
let Some(key) = master_key.as_ref() else {
return map;
};
for ev in env_vars {
if let Ok(plaintext) = sh0_auth::crypto::decrypt(key, &ev.value_encrypted) {
map.insert(
ev.key.clone(),
String::from_utf8_lossy(&plaintext).into_owned(),
);
}
}
map
}Then, before building the BackupSource, we query and decrypt:
rustlet env_vars = EnvVar::list_by_app_id(&pool, &app.id)?;
let env_map = decrypt_env_map(&master_key, &env_vars);
let (db_name, db_user, db_password) = match engine.as_str() {
"postgres" | "postgresql" | "timescaledb" | "pgvector" => {
let name = env_map.get("POSTGRES_DB")
.cloned()
.unwrap_or_else(|| "postgres".into());
let user = env_map.get("POSTGRES_USER")
.cloned()
.unwrap_or_else(|| "postgres".into());
let pass = env_map.get("POSTGRES_PASSWORD").cloned();
(name, user, pass)
}
"mysql" | "mariadb" => {
let name = env_map.get("MYSQL_DATABASE")
.cloned()
.unwrap_or_else(|| "app".into());
let user = "root".to_string();
let pass = env_map.get("MYSQL_ROOT_PASSWORD").cloned();
(name, user, pass)
}
"mongodb" | "mongo" => {
let name = env_map.get("MONGO_INITDB_DATABASE")
.cloned()
.unwrap_or_else(|| "app".into());
let user = env_map.get("MONGO_INITDB_ROOT_USERNAME")
.cloned()
.unwrap_or_else(|| "admin".into());
let pass = env_map.get("MONGO_INITDB_ROOT_PASSWORD").cloned();
(name, user, pass)
}
_ => (app.name.clone(), "root".to_string(), None),
};Each database engine has its own env var convention. PostgreSQL uses POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD. MySQL uses MYSQL_DATABASE, MYSQL_ROOT_PASSWORD. MongoDB uses MONGO_INITDB_DATABASE, MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD. The fallback uses app.name only for engines we do not recognize.
The Same Fix in Two Places
The credential resolution needed to happen in both the trigger handler (backups.rs) and the cron scheduler (scheduler.rs). The trigger handler runs when a user clicks "Backup Now." The scheduler runs every 60 seconds and checks for due schedules.
Both paths had the same db_name: app.name bug. Both needed the same env var lookup. We added the decrypt_env_map and extract_db_credentials helpers in both files (they are small enough that extracting a shared crate was not worth the dependency complexity).
The scheduler needed access to the master key through the BackupEngine:
rustpub(crate) master_key: Option<Arc<MasterKey>>,We made the field pub(crate) so the scheduler (in the same crate) could read it without a getter method.
The Volume Path Problem
The same session revealed a parallel bug in volume backups. When no mount records existed in the database (common for template-deployed apps), the scheduler defaulted to /data as the volume path. PostgreSQL stores data in /var/lib/postgresql/data. MySQL uses /var/lib/mysql. The Docker archive API returned 404 - Could not find the file /data in container.
The fix was a stack-aware default map:
rustfn default_volume_path(stack: &str) -> &'static str {
match stack {
"postgres" | "postgresql" => "/var/lib/postgresql/data",
"mysql" | "mariadb" => "/var/lib/mysql",
"mongodb" | "mongo" => "/data/db",
"redis" | "dragonfly" => "/data",
"clickhouse" => "/var/lib/clickhouse",
"cassandra" | "scylladb" => "/var/lib/cassandra",
_ => "/data",
}
}These paths are Docker image conventions, not configuration -- every postgres:16-alpine image stores data in /var/lib/postgresql/data. By knowing the stack, we know the path.
What This Teaches About Template Systems
Template-deployed services carry their identity in two places: the app record (name, stack, status) and the env vars (actual runtime configuration). The app record is the human-facing identity. The env vars are the machine-facing identity. Any feature that interacts with the runtime -- backups, monitoring, credentials display -- must read the env vars, not the app record.
The credentials card already knew this. The backup engine did not. The fix was not technically complex (30 lines of env var decryption). The lesson was architectural: when a template creates a service, the template's variables are the source of truth for that service's identity.
The next time we build a feature that touches template-deployed services -- log streaming, performance analysis, connection pooling -- we will start with the env vars, not the app name.
Next in the series: Docker Volumes Are Not Host Paths -- why tar::Builder::append_dir_all fails for Docker volumes, how the Docker archive API works, and the binary data corruption bug in the multiplexed stream parser.