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

オープン
  • 何か問題がありますか？
#4,749 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

@AbarnaaSree がすでに取り組んでいます。

2026年8月23日 から。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
48/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
postgres, typescript
領域
backend-api-design, databases, security

調査の方向性

まず、AgentsHost の公開コンストラクターと createDb の宣言を追跡し、次に src/db/schema.ts と dist/index.d.ts を調べて、スキーマにバインドされた DrizzleDB とパッケージのエクスポートを理解します。起動時のログ出力経路については dist/entrypoint.js を確認します。呼び出し元が公開エクスポートを通じて正しくバインドされたデータベースを使用して PgClient を構築でき、URL の構築が引き続き機能し、起動ログに接続 URL が含まれなければ完了です。

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
TypeScript
スター
10.4k
フォーク
399
30日以内にマージされた PR はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

electric-sql/electric のほかの issue

electric-sql/electric の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。