Allow AgentsHost to be constructed from a caller-owned PgClient without a schema-bound DrizzleDB

Aperta
  • Qualcosa non va?
#4,749 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

@AbarnaaSree ci sta già lavorando.

Dal 23/8/2026.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
postgres, typescript
Ambito
backend-api-design, databases, security

Direzione di ricerca

Inizia tracciando il costruttore pubblico di AgentsHost e le dichiarazioni di createDb, quindi esamina src/db/schema.ts e dist/index.d.ts per comprendere la DrizzleDB associata allo schema e le esportazioni del pacchetto. Esamina dist/entrypoint.js per il percorso di logging dell'avvio. Il lavoro è completato quando la costruzione di PgClient da parte del chiamante utilizza un database associato correttamente tramite le esportazioni pubbliche, la costruzione dell'URL continua a funzionare e il log di avvio non contiene alcun URL di connessione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

electric-agents

Problem

AgentsHost cannot be constructed by a caller that supplies its own configured PostgreSQL client, even though AgentsHostOptions looks like it supports exactly that.

interface AgentsHostOptions {
  db: DrizzleDB;
  pgClient: PgClient;
  ...
}

type DrizzleDB = ReturnType<typeof drizzle<typeof schema_d_exports>>;
type PgClient  = ReturnType<typeof postgres>;

declare function createDb(postgresUrl: string): { db: DrizzleDB; client: PgClient };

pgClient is caller-owned, which is good. But db is also required and its type is bound to the package's schema namespace, and:

  1. createDb is the only public constructor and it takes a URL string. A caller that must configure its own connection policy — a custom CA, an exact TLS server name, a certificate pin, pooling rules — cannot use it. Our deployment standard forbids passing a credential through a connection URL at all.
  2. schema_d_exports is declare namespaced in dist/index.d.ts but is not in the package's export list and not among the runtime exports. src/db/schema.ts ships in the tarball, but exports only maps . and ./package.json, so reaching it means a private import.
The part that makes this worth fixing rather than working around

There is a workaround that looks completely clean and is not:

const host = new AgentsHost({ db: drizzle(pgClient), pgClient })

This compiles with no any and no cast, because drizzle's schema parameter is optional and TypeScript infers TSchema from the contextual DrizzleDB. At runtime it binds zero tables against the 21 the type declares:

{"compiles":true,"usedAnyOrCast":false,"boundSchemaKeysAtRuntime":[],"declaredSchemaTablesInTypes":21}

It works today only because the shipped bundle never calls drizzle's relational query API. It would break silently on any upgrade that starts doing so, and nothing in the type system or in a review diff would catch it. So the safe-looking path is the dangerous one, which is a good argument for closing it in the API.

Two smaller related gaps for a full self-managed host: TenantContext.pgDb: DrizzleDB needs the same value, and getPrincipalFromRequest is not exported, so a caller has to reimplement the electric-principal header contract.

Requested behavior

Any one of these closes it:

  • Option A: add a createDb(client: PgClient) overload alongside the URL form.
  • Option B: make AgentsHostOptions.db optional and derive it from pgClient when absent.
  • Option C: export the schema namespace from the package root so callers can construct a correctly bound DrizzleDB themselves.

Option B is the smallest for callers. Option C is the most flexible. Option A matches the shape of #4747.

Relationship to #4746 and #4747

#4747 adds a caller-owned PgClient overload to runMigrations. That is necessary but not sufficient: it lets a caller run migrations with its own client, and this issue is about then constructing the host with that same client. Both are needed for a self-managed deployment that never puts a credential in a URL.

Separate, and arguably more urgent

dist/entrypoint.js logs the connection URL at startup:

console.log(`Postgres: ${started.options.postgresUrl}`)

postgresUrl carries the password. Any deployment that runs the shipped entrypoint prints its database credential to stdout, where it lands in pod logs and whatever aggregates them. That is independent of everything above and worth fixing on its own; happy to send a PR for it if that is useful.

Acceptance criteria

  • A consumer can construct AgentsHost with a PgClient it configured itself, through public exports only, with no private import, no any, and no cast.
  • The resulting host has a correctly schema-bound db, so a future upstream use of the relational query API does not fail at runtime.
  • The existing URL-based construction keeps working.
  • The startup log does not contain the connection URL.
Lingua principale
TypeScript
Stelle
10.4k
Fork
399
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di electric-sql/electric

Tutte le issue di electric-sql/electric

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.