Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Define a canonical PostgreSQL configuration path for Compose and cloud startup

Open
  • Is something wrong?
#949 1 comment 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, docker-compose, go, postgresql
Domain
databases, devops

Research direction

Start with the published Compose config (docker-compose / GHCR reference) and the .env docs that set POSTGRES_* versus ENGRAM_DATABASE_URL, then locate cloudstore.New and its PingContext call to see where the real connection is made. Also read PR #691's discussion to learn why pg_isready was rejected. Done means one validated canonical config path, URI-safe credential handling, and a fresh-volume startup test showing Compose initialization and the cloud store's connection succeed together; note the issue requires status:approved before any PR.

Written by the indexing model from the issue text.

Description

priority:medium status:needs-review type:feature
📋 Pre-flight Checks
  • I have searched existing issues and this is not a duplicate
  • I understand this issue needs status:approved before a PR can be opened
🔍 Problem Description

The published GHCR reference Compose configuration initializes PostgreSQL with POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB, while the cloud service independently connects through ENGRAM_DATABASE_URL. cloudstore.New performs the actual PingContext.

The documented .env therefore duplicates database identity and credential information in POSTGRES_* values and in the DSN, without one canonical user-facing configuration path. This creates an observable contradiction when the two representations do not agree, particularly for URI-sensitive password values.

💡 Proposed Solution

Define one canonical, safely validated PostgreSQL configuration path for Compose initialization and the cloud service’s runtime connection.

The intended behavior should:

  • make the relationship between PostgreSQL initialization values and ENGRAM_DATABASE_URL explicit and safely validated;
  • handle URI-sensitive credential values correctly when constructing or accepting a DSN;
  • ensure readiness checks are not treated as proof that the runtime credentials and database target are usable;
  • add a behavior-level fresh-volume startup test proving initialization and the cloud store’s actual connection path succeed together.
📦 Affected Area

Store (database, queries)

🔄 Alternatives Considered

Continue documenting POSTGRES_* and ENGRAM_DATABASE_URL as independently supplied values. This leaves database identity and credentials duplicated and does not provide a canonical or validated relationship between them.

📎 Additional Context

PR #691’s pg_isready healthcheck change was closed as not root-causal. pg_isready can report readiness without correct user or database values, whereas the actual cloud connection is established by cloudstore.New through PingContext.

This report does not claim a production incident, a local Docker reproduction, or data loss. Docker and pg_isready were unavailable locally.

Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
11h 17m
Merged PRs (30d)
334

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

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 Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.