@lakeql/datasource defines the adapter-neutral contracts. It imports nothing engine-specific: no Trino, Fabric, GraphQL, or Kysely. The core stays independent of any backend.
The Core Interfaces #
-
DataSource— executes SQL, exposes metadata and DDL where supported, and forwards auth and request options to the backend. -
DataSourceReadStrategy— orchestrates and validates a read. -
DataSourceWriteStrategy— implements a write path (see writing ). -
AdapterFactory— constructs the data source and strategies from a validated connection config.
Normalized Errors #
Adapters translate engine errors into a common hierarchy rooted at DataSourceError. Each error carries a category: auth, query, network, timeout, cancelled, or unsupported. The API layer maps those categories to GraphQL error codes and HTTP statuses, so clients see consistent errors regardless of the engine.
DataSourceValidationError is a separate Error subclass, not a DataSourceError. It carries field/value rather than a category and falls through to the generic 500 mapping. See error handling.
Capabilities #
An adapter reports its DataSourceCapabilities. A write strategy is only offered when the adapter reports the capabilities it needs. DDL support, for example, is not implied by the ability to run INSERT.
For the complete contract, see the API reference.