Architecture

Status: intended design. Public types and connect() live in core. Driver and hosted provider packages are not implemented yet. The shape is one core, drivers for database types, and hosted providers that reuse a driver.

12345db-sdk                 core types, connect(), safety helpers
  @db-sdk/postgres     Postgres driver (first)
  @db-sdk/firestore    Firestore driver (first)
  @db-sdk/supabase     hosted provider → Postgres driver
  @db-sdk/<name>       later drivers or hosted providers

Provider contract

connect({ provider }) opens a handle to an existing database; it does not create one. Each provider has an id (what you stored) and a driver (the query family).

123456789interface DatabaseProvider<TQuery = unknown> {
  readonly id: string;
  readonly driver: string;
  readonly capability: "relational" | "document";
  test(signal?: AbortSignal): Promise<void>;
  introspect(signal?: AbortSignal): Promise<Catalog>;
  query(input: TQuery, signal?: AbortSignal): Promise<QueryResult>;
  close(): Promise<void>;
}

Catalog and results

Introspection returns one catalog shape so UIs and models share a picture of the store. Relational drivers fill it from information_schema. Document drivers sample documents and union keys. Caching is a host concern.

Capabilities group tools for hosts. They do not flatten drivers into one AST. A later MongoDB driver should use Mongo's read API, not Firestore's filter list.

Adding a driver or hosted provider

• Drivers implement test, introspect, query, and close for a database type.
• Hosted providers own product OAuth/API, then open an existing driver.
• Map native types into catalog field strings.
• Enforce that driver's read-only policy in query.
• Export a factory; set id and driver (often the same for raw drivers).