Creating a Client

SqbClient is the entry point to @sqb/connect. It owns a connection pool for a single database, resolves the driver ("adapter") you want to talk to, and gives you execute() and acquire() methods to run queries against it.

Registering an adapter

@sqb/connect itself does not ship any database driver. Each driver lives in its own package (e.g. @sqb/postgres, @sqb/mysql, @sqb/sqlite) and registers itself as a side effect of being imported. Importing the package is enough — there is nothing else to wire up:

import '@sqb/postgres'; // registers the "postgres" driver/dialect
import { SqbClient } from '@sqb/connect';

Under the hood, an adapter package calls AdapterRegistry.register() at module load time. SqbClient then looks the adapter up from that registry when you construct it. If you forget the import, SqbClient's constructor throws because it can't find a matching driver or dialect.

The built-in adapter packages, and the dialect/driver names each one registers under:

Package	dialect	driver	npm driver package
@sqb/postgres	'postgres'	'postgrejs'	PostgreJS
@sqb/mysql	'mysql'	'mysql2'	mysql2
@sqb/mariadb	'mariadb'	'mariadb'	mariadb
@sqb/mssql	'mssql'	'mssql'	mssql
@sqb/oracle	'oracle'	'oracledb'	oracledb
@sqb/sqlite	'sqlite'	'sqlite'	none — Node's built-in node:sqlite (or Bun's bun:sqlite)
@sqb/sqljs	'sqlite'	'sqljs'	sql.js

@sqb/sqlite and @sqb/sqljs share the 'sqlite' dialect — if you ever import both in the same process, pass driver instead of dialect to SqbClient to say which one you mean. See Choosing a Database Adapter for driver details and when to pick each one.

Constructing a client

import '@sqb/postgres';
import { type ClientConfiguration, SqbClient } from '@sqb/connect';

const client = new SqbClient({
  dialect: 'postgres',
  host: 'localhost',
  database: 'mydb',
});

The constructor accepts a single ClientConfiguration object and throws a TypeError if it isn't given an object at all, or an Error if it can't resolve an adapter (see below).

Selecting the adapter: dialect vs driver

You must supply either dialect or driver — the constructor throws You must provide one of "driver" or "dialect" properties if neither is set.

• dialect looks the adapter up by its SQL dialect name (e.g. 'postgres', 'mysql', 'sqlite') via AdapterRegistry.findDialect().
• driver looks the adapter up by its driver package name via AdapterRegistry.findDriver(). This is only needed when more than one adapter package targets the same dialect and you need to pick a specific one.

If the matching adapter isn't registered (i.e. its package was never imported), the constructor throws No database adapter registered for "<name>" driver or ..."<name>" dialect.

ClientConfiguration fields

Field	Type	Description
dialect	string	SQL dialect to resolve an adapter for.
driver	string	Driver package name to resolve an adapter for.
name	string	An arbitrary connection name.
host	string	Database server address.
port	number	Database listener port.
user	string	Database username.
password	string	Database password.
database	string	Database name.
schema	string	Database schema to use.
driverOptions	any	Extra options passed straight through to the underlying driver.
pool	PoolConfiguration	Connection pool tuning — see Connection Pooling.
defaults	ClientDefaults	Default values applied to every query executed through this client — see Executing Queries.

host, port, user, password, database, schema and driverOptions are all optional at the @sqb/connect level; whether they're required, and what other driver-specific options are accepted through driverOptions, depends on the adapter package you're using.

The whole configuration object (minus pool and defaults, which are consumed by SqbClient itself) is forwarded to the adapter's connect() function whenever the pool needs to create a new physical connection.

Client getters

Once constructed, a few read-only getters are available:

• client.dialect — the resolved adapter's dialect name.
• client.driver — the resolved adapter's driver name.
• client.defaults — the effective ClientDefaults (the object you passed, or {}).
• client.pool — the underlying lightning-pool pool instance (see Connection Pooling).
• client.isClosed — true once the pool has been closed.

Next steps

• Connection Pooling — tune pool size, timeouts and validation.
• Acquiring Connections — get a SqbConnection out of the pool.
• Executing Queries — run SQL or a Query builder object and read the defaults that apply.