Connect | OKModel

connect()Anatomy

export const db = connect(

url,url

{

schema,required

},

);

Target

A connection string, a pool from open, or { primary, replicas }. A string or a pool returns the client. A topology returns a promise.

Schema

The schema types the client. The other decisions are the pages below. close() is on this page.

Import connect from the driver you installed. The process keeps one client. Use a TCP URL such as postgres://localhost:5432/app. A Windows named pipe is not a URL this version opens.

The schema

The client is typed by the schema you pass. A Register augmentation, which okm init writes, feeds the Row, Insert, and Update helper types when no schema is passed.

The declaration

The list is how often you reach for each part while opening a client. The target and the schema come first.

db.ts

import { connect } from "okmodel/pg/postgresjs";
import { schema, table, t } from "okmodel/pg";

const notes = table("notes", {
  id: t.identity(),
  title: t.text(),
});

const app = schema({ tables: [notes] });

export const db = connect(process.env.DATABASE_URL!, { schema: app });

Order	Page	You use it for
1	Drivers	The import.
2	Target	A URL, a pool, or memory.
3	Topology	A primary and its replicas.
4	Check	The server, the floor, and the catalog hash.
5	Session	Pool size, TLS, search path, and deadlines.
6	Session settings	`sessionSettings()` and `db.with()` GUC values.
7	Limits	Defaults for `find`, `page`, `groupBy`, and includes.
8	Errors	HTTP statuses and row values.
9	Generators	`uuidv4`, `uuidv7`, and `okid`.
10	Observability	Observers and OpenTelemetry spans.

Close

A script calls close() when it is done. A server keeps the client for the life of the process. The call ends the pool only when this client opened it. Who opened it is Target.

Client	`close()`
Opened the pool	Ends that pool.
Adopted a pool	Resolves. The pool stays open.
`using()`	Absent on that client.

await using is that call at the end of the block. It calls the same close(). The client has [Symbol.asyncDispose] when the runtime defines that symbol. A runtime without the symbol leaves the client unchanged.

A finished script should call close() or use await using. Set idleTimeoutMs: 0 only when a short script must exit without that call on a driver whose idle timer would otherwise keep the process alive.

script.ts

import { connect } from "okmodel/pg/postgresjs";
import { schema, table, t } from "okmodel/pg";

const notes = table("notes", {
  id: t.identity(),
  title: t.text(),
});

const app = schema({ tables: [notes] });

export async function read() {
  await using db = connect(process.env.DATABASE_URL!, { schema: app }); 
  await db.notes.find({ limit: 1 });
}

A second close() waits on the same close when this client opened the pool. The first call starts the close. A later call returns that promise. for() and unscoped() reuse it. An adopted pool resolves without closing it, on every call.

using() returns a client with no close. The root close() stops the probes and closes every pool that connect opened.

close() before the check settles, on a client that opened the pool, does not reject connected when the check succeeds. When the check fails, the rejection is The client was closed before it connected. Await connected before close(), or do not close it before use. That promise is Check.

The declaration

Close

On this page