electric-sql / electric-sql/electric
Allow AgentsHost to be constructed from a caller-owned PgClient without a schema-bound DrizzleDB
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Problem
`AgentsHost` cannot be constructed by a caller that supplies its own configured PostgreSQL client, even though `AgentsHostOptions` looks like it supports exactly that.
```ts
interface AgentsHostOptions {
db: DrizzleDB;
pgClient: PgClient;
...
}
type DrizzleDB = ReturnType>;
type PgClient = ReturnType;
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 namespace`d 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:
```ts
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:
```json
{"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](https://github.com/electric-sql/electric/pull/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:
```js
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.
Contributor guide
Research direction
Start by tracing the public AgentsHost constructor and createDb declarations, then inspect src/db/schema.ts and dist/index.d.ts to understand the schema-bound DrizzleDB and package exports. Review dist/entrypoint.js for the startup logging path. Done means caller-owned PgClient construction uses a correctly bound database through public exports, URL construction still works, and the startup log contains no connection URL.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgres, typescript
- Domain
- backend-api-design, databases, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100