Adapter

Adapter is the interface a database driver package (e.g. @sqb/postgres) implements to plug into @sqb/connect. Application code doesn't normally implement this itself — it's documented here because it's exported from @sqb/connect and is useful when reading or writing an adapter package. See Creating a Client and AdapterRegistry for how adapters are registered and resolved.

interface Adapter {
  driver: string;
  dialect: string;
  features?: Adapter.Features;
  connect: (config: ClientConfiguration) => Promise<Adapter.Connection>;
}

Field	Type	Description
driver	string	The driver package's own name, matched against ClientConfiguration.driver.
dialect	string	The SQL dialect this adapter serializes for, matched against ClientConfiguration.dialect.
features	Adapter.Features	Optional feature flags (see below).
connect	(config: ClientConfiguration) => Promise<Adapter.Connection>	Opens one physical connection — called by the pool's create() factory method.

Adapter.Connection

The physical connection object returned by connect(), and what client.pool actually pools.

interface Adapter.Connection {
  sessionId: any;
  execute: (request: QueryRequest) => Promise<Adapter.Response>;
  close: () => Promise<void>;
  reset: () => Promise<void>;
  test: () => Promise<void>;
  startTransaction: () => Promise<void>;
  setSavepoint?: (savepoint: string) => Promise<void>;
  releaseSavepoint?: (savepoint: string) => Promise<void>;
  rollbackSavepoint?: (savepoint: string) => Promise<void>;
  commit: () => Promise<void>;
  rollback: () => Promise<void>;
  setSchema?: (schema: string) => Promise<void>;
  getSchema?: () => Promise<string>;
  onGenerateQuery?: (request: QueryRequest, query: Query) => void;
  getInTransaction?: () => boolean;
}

setSavepoint/releaseSavepoint/rollbackSavepoint and setSchema/getSchema are optional — SqbConnection throws a descriptive error when you call the corresponding method against an adapter that doesn't implement it.

Adapter.Cursor

The cursor object an adapter returns in Adapter.Response.cursor, wrapped by Cursor.

interface Adapter.Cursor {
  readonly isClosed: boolean;
  readonly rowType: RowType;
  close: () => Promise<void>;
  fetch: (rows: number) => Promise<any[] | undefined>;
}

Adapter.Response

What Adapter.Connection.execute() resolves with.

interface Adapter.Response {
  fields?: Adapter.Field[];
  rows?: Record<string, any>[] | any[][];
  rowType?: RowType;
  cursor?: Adapter.Cursor;
  rowsAffected?: number;
}

Adapter.Field

Raw column metadata as reported by the driver, before naming-strategy/index wrapping into FieldInfo.

interface Adapter.Field {
  fieldName: string;
  dataType: string;
  jsType: string;
  isArray?: boolean;
  elementDataType?: string;
  nullable?: boolean;
  fixedLength?: boolean;
  size?: number;
  precision?: number;
  _inf: any;
}

Adapter.Features

Optional capability flags an adapter can declare.

interface Adapter.Features {
  cursor?: boolean;
  schema?: boolean;
  fetchAsString?: DataType[];
  positionalParams?: boolean;
}