1045 lines
31 KiB
TypeScript
1045 lines
31 KiB
TypeScript
import type * as BunSQLite from "bun:sqlite";
|
|
|
|
declare module "bun" {
|
|
/**
|
|
* A connection reserved from the pool with {@link SQL.reserve}. Call
|
|
* {@link release} to return it to the pool.
|
|
*/
|
|
interface ReservedSQL extends SQL, Disposable {
|
|
/**
|
|
* Releases the client back to the connection pool
|
|
*/
|
|
release(): void;
|
|
}
|
|
|
|
type ArrayType =
|
|
| "BOOLEAN"
|
|
| "BYTEA"
|
|
| "CHAR"
|
|
| "NAME"
|
|
| "TEXT"
|
|
| "CHAR"
|
|
| "VARCHAR"
|
|
| "SMALLINT"
|
|
| "INT2VECTOR"
|
|
| "INTEGER"
|
|
| "INT"
|
|
| "BIGINT"
|
|
| "REAL"
|
|
| "DOUBLE PRECISION"
|
|
| "NUMERIC"
|
|
| "MONEY"
|
|
| "OID"
|
|
| "TID"
|
|
| "XID"
|
|
| "CID"
|
|
| "JSON"
|
|
| "JSONB"
|
|
| "JSONPATH"
|
|
| "XML"
|
|
| "POINT"
|
|
| "LSEG"
|
|
| "PATH"
|
|
| "BOX"
|
|
| "POLYGON"
|
|
| "LINE"
|
|
| "CIRCLE"
|
|
| "CIDR"
|
|
| "MACADDR"
|
|
| "INET"
|
|
| "MACADDR8"
|
|
| "DATE"
|
|
| "TIME"
|
|
| "TIMESTAMP"
|
|
| "TIMESTAMPTZ"
|
|
| "INTERVAL"
|
|
| "TIMETZ"
|
|
| "BIT"
|
|
| "VARBIT"
|
|
| "ACLITEM"
|
|
| "PG_DATABASE"
|
|
| (string & {});
|
|
|
|
/**
|
|
* An array parameter created by {@link SQL.array}
|
|
*/
|
|
interface SQLArrayParameter {
|
|
/**
|
|
* The array values, serialized into a single string
|
|
*/
|
|
serializedValues: string;
|
|
/**
|
|
* The element type of the array, for example `"INT"`
|
|
*/
|
|
arrayType: ArrayType;
|
|
}
|
|
|
|
/**
|
|
* The client passed to transaction callbacks ({@link SQL.begin},
|
|
* {@link SQL.transaction}). Extends {@link SQL} with savepoints.
|
|
*/
|
|
interface TransactionSQL extends SQL {
|
|
/**
|
|
* Creates a savepoint within the current transaction
|
|
*/
|
|
savepoint<T>(name: string, fn: SQL.SavepointContextCallback<T>): Promise<T>;
|
|
savepoint<T>(fn: SQL.SavepointContextCallback<T>): Promise<T>;
|
|
|
|
/**
|
|
* Reserves a connection from the pool and returns a client that wraps
|
|
* that single connection.
|
|
*
|
|
* Inside a transaction, `reserve()` returns a brand new connection, not
|
|
* one related to the transaction. This matches the behaviour of the
|
|
* `postgres` package.
|
|
*/
|
|
reserve(): Promise<ReservedSQL>;
|
|
}
|
|
|
|
namespace SQL {
|
|
class SQLError extends Error {
|
|
constructor(message: string);
|
|
}
|
|
|
|
class PostgresError extends SQLError {
|
|
public readonly code: string;
|
|
public readonly errno?: string | undefined;
|
|
public readonly detail?: string | undefined;
|
|
public readonly hint?: string | undefined;
|
|
public readonly severity?: string | undefined;
|
|
public readonly position?: string | undefined;
|
|
public readonly internalPosition?: string | undefined;
|
|
public readonly internalQuery?: string | undefined;
|
|
public readonly where?: string | undefined;
|
|
public readonly schema?: string | undefined;
|
|
public readonly table?: string | undefined;
|
|
public readonly column?: string | undefined;
|
|
public readonly dataType?: string | undefined;
|
|
public readonly constraint?: string | undefined;
|
|
public readonly file?: string | undefined;
|
|
public readonly line?: string | undefined;
|
|
public readonly routine?: string | undefined;
|
|
|
|
constructor(
|
|
message: string,
|
|
options: {
|
|
code: string;
|
|
errno?: string | undefined;
|
|
detail?: string;
|
|
hint?: string | undefined;
|
|
severity?: string | undefined;
|
|
position?: string | undefined;
|
|
internalPosition?: string;
|
|
internalQuery?: string;
|
|
where?: string | undefined;
|
|
schema?: string;
|
|
table?: string | undefined;
|
|
column?: string | undefined;
|
|
dataType?: string | undefined;
|
|
constraint?: string;
|
|
file?: string | undefined;
|
|
line?: string | undefined;
|
|
routine?: string | undefined;
|
|
},
|
|
);
|
|
}
|
|
|
|
class MySQLError extends SQLError {
|
|
public readonly code: string;
|
|
public readonly errno?: number | undefined;
|
|
public readonly sqlState?: string | undefined;
|
|
constructor(message: string, options: { code: string; errno: number | undefined; sqlState: string | undefined });
|
|
}
|
|
|
|
class SQLiteError extends SQLError {
|
|
public readonly code: string;
|
|
public readonly errno: number;
|
|
public readonly byteOffset?: number | undefined;
|
|
|
|
constructor(message: string, options: { code: string; errno: number; byteOffset?: number | undefined });
|
|
}
|
|
|
|
type AwaitPromisesArray<T extends Array<PromiseLike<any>>> = {
|
|
[K in keyof T]: Awaited<T[K]>;
|
|
};
|
|
|
|
type ContextCallbackResult<T> = T extends Array<PromiseLike<any>> ? AwaitPromisesArray<T> : Awaited<T>;
|
|
type ContextCallback<T, SQL> = (sql: SQL) => Bun.MaybePromise<T>;
|
|
|
|
interface SQLiteOptions extends BunSQLite.DatabaseOptions {
|
|
adapter?: "sqlite";
|
|
|
|
/**
|
|
* Path to the database file
|
|
*
|
|
* Examples:
|
|
*
|
|
* - `sqlite://:memory:`
|
|
* - `sqlite://./path/to/database.db`
|
|
* - `sqlite:///Users/bun/projects/my-app/database.db`
|
|
* - `./dev.db`
|
|
* - `:memory:`
|
|
*
|
|
* @default ":memory:"
|
|
*/
|
|
filename?: URL | ":memory:" | (string & {}) | undefined;
|
|
|
|
/**
|
|
* Called when a connection attempt completes.
|
|
* Receives an `Error` on failure, or `null` on success.
|
|
*/
|
|
onconnect?: ((err: Error | null) => void) | undefined;
|
|
|
|
/**
|
|
* Called when a connection is closed.
|
|
* Receives the closing `Error`, or `null`.
|
|
*/
|
|
onclose?: ((err: Error | null) => void) | undefined;
|
|
}
|
|
|
|
interface PostgresOrMySQLOptions {
|
|
/**
|
|
* Connection URL, for example `postgres://user:pass@localhost:5432/mydb`
|
|
*/
|
|
url?: URL | string | undefined;
|
|
|
|
/**
|
|
* Database server hostname
|
|
* @deprecated Prefer {@link hostname}
|
|
* @default "localhost"
|
|
*/
|
|
host?: string | undefined;
|
|
|
|
/**
|
|
* Database server hostname
|
|
* @default "localhost"
|
|
*/
|
|
hostname?: string | undefined;
|
|
|
|
/**
|
|
* Database server port number
|
|
* @default 5432
|
|
*/
|
|
port?: number | string | undefined;
|
|
|
|
/**
|
|
* Database user for authentication
|
|
* @default "postgres"
|
|
*/
|
|
username?: string | undefined;
|
|
|
|
/**
|
|
* Database user for authentication (alias for username)
|
|
* @deprecated Prefer {@link username}
|
|
* @default "postgres"
|
|
*/
|
|
user?: string | undefined;
|
|
|
|
/**
|
|
* Database password for authentication
|
|
* @default ""
|
|
*/
|
|
password?: string | (() => MaybePromise<string>) | undefined;
|
|
|
|
/**
|
|
* Database password for authentication (alias for password)
|
|
* @deprecated Prefer {@link password}
|
|
* @default ""
|
|
*/
|
|
pass?: string | (() => MaybePromise<string>) | undefined;
|
|
|
|
/**
|
|
* Name of the database to connect to
|
|
* @default The username value
|
|
*/
|
|
database?: string | undefined;
|
|
|
|
/**
|
|
* Name of the database to connect to (alias for database)
|
|
* @deprecated Prefer {@link database}
|
|
* @default The username value
|
|
*/
|
|
db?: string | undefined;
|
|
|
|
/**
|
|
* Database adapter/driver to use
|
|
* @default "postgres"
|
|
*/
|
|
adapter?: "postgres" | "mysql" | "mariadb";
|
|
|
|
/**
|
|
* Maximum time in seconds a connection can sit idle before it is closed
|
|
* @default 0 (no timeout)
|
|
*/
|
|
idleTimeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum time in seconds a connection can sit idle before it is closed (alias for idleTimeout)
|
|
* @deprecated Prefer {@link idleTimeout}
|
|
* @default 0 (no timeout)
|
|
*/
|
|
idle_timeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum time in seconds to wait when establishing a connection
|
|
* @default 30
|
|
*/
|
|
connectionTimeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum time in seconds to wait when establishing a connection (alias for connectionTimeout)
|
|
* @deprecated Prefer {@link connectionTimeout}
|
|
* @default 30
|
|
*/
|
|
connection_timeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum time in seconds to wait when establishing a connection (alias
|
|
* for connectionTimeout)
|
|
* @deprecated Prefer {@link connectionTimeout}
|
|
* @default 30
|
|
*/
|
|
connectTimeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum time in seconds to wait when establishing a connection (alias
|
|
* for connectionTimeout)
|
|
* @deprecated Prefer {@link connectionTimeout}
|
|
* @default 30
|
|
*/
|
|
connect_timeout?: number | undefined;
|
|
|
|
/**
|
|
* Maximum lifetime in seconds of a connection
|
|
* @default 0 (no maximum lifetime)
|
|
*/
|
|
maxLifetime?: number | undefined;
|
|
|
|
/**
|
|
* Maximum lifetime in seconds of a connection (alias for maxLifetime)
|
|
* @deprecated Prefer {@link maxLifetime}
|
|
* @default 0 (no maximum lifetime)
|
|
*/
|
|
max_lifetime?: number | undefined;
|
|
|
|
/**
|
|
* Whether to use TLS/SSL for the connection. A string selects the
|
|
* SSL mode (`"disable"`, `"allow"`, `"prefer"`, `"require"`, `"verify-ca"`, `"verify-full"`).
|
|
* @default false
|
|
*/
|
|
tls?:
|
|
| Bun.BunFile
|
|
| TLSOptions
|
|
| boolean
|
|
| "disable"
|
|
| "allow"
|
|
| "prefer"
|
|
| "require"
|
|
| "verify-ca"
|
|
| "verify-full"
|
|
| undefined;
|
|
|
|
/**
|
|
* Whether to use TLS/SSL for the connection (alias for tls)
|
|
* @deprecated Prefer {@link tls}
|
|
* @default false
|
|
*/
|
|
ssl?:
|
|
| Bun.BunFile
|
|
| TLSOptions
|
|
| boolean
|
|
| "disable"
|
|
| "allow"
|
|
| "prefer"
|
|
| "require"
|
|
| "verify-ca"
|
|
| "verify-full"
|
|
| undefined;
|
|
|
|
/**
|
|
* Unix domain socket path for connection
|
|
* @default undefined
|
|
*/
|
|
path?: string | undefined;
|
|
|
|
/**
|
|
* Called when a connection attempt completes.
|
|
* Receives an `Error` on failure, or `null` on success.
|
|
*/
|
|
onconnect?: ((err: Error | null) => void) | undefined;
|
|
|
|
/**
|
|
* Called when a connection is closed.
|
|
* Receives the closing `Error`, or `null`.
|
|
*/
|
|
onclose?: ((err: Error | null) => void) | undefined;
|
|
|
|
/**
|
|
* Postgres client runtime configuration options
|
|
*
|
|
* @see https://www.postgresql.org/docs/current/runtime-config-client.html
|
|
*/
|
|
connection?: Record<string, string | boolean | number> | undefined;
|
|
|
|
/**
|
|
* Maximum number of connections in the pool
|
|
* @default 10
|
|
*/
|
|
max?: number | undefined;
|
|
|
|
/**
|
|
* Return values outside the i32 range as `BigInt`. By default they are
|
|
* returned as strings.
|
|
* @default false
|
|
*/
|
|
bigint?: boolean | undefined;
|
|
|
|
/**
|
|
* Automatic creation of prepared statements
|
|
* @default true
|
|
*/
|
|
prepare?: boolean | undefined;
|
|
|
|
/**
|
|
* MySQL only. Allow the client to request the server's RSA public key
|
|
* during `caching_sha2_password` / `sha256_password` authentication when
|
|
* the connection is not protected by TLS. Disabled by default because a
|
|
* network attacker can substitute their own key and recover the
|
|
* plaintext password. Enable only for trusted local connections, or use
|
|
* TLS instead.
|
|
* @default false
|
|
*/
|
|
allowPublicKeyRetrieval?: boolean | undefined;
|
|
}
|
|
|
|
/**
|
|
* Configuration options for SQL client connection and behavior
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const config: Bun.SQL.Options = {
|
|
* host: 'localhost',
|
|
* port: 5432,
|
|
* user: 'dbuser',
|
|
* password: 'secretpass',
|
|
* database: 'myapp',
|
|
* idleTimeout: 30,
|
|
* max: 20,
|
|
* onconnect: (err) => {
|
|
* if (!err) console.log('Connected to database');
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
type Options = SQLiteOptions | PostgresOrMySQLOptions;
|
|
|
|
/** One registration made by {@link SQL.listen}. */
|
|
interface ListenSubscription extends AsyncDisposable {
|
|
readonly channel: string;
|
|
/**
|
|
* Remove this registration. Resolves once the channel is no longer
|
|
* subscribed, or immediately when other registrations on it remain.
|
|
* Idempotent; `await using` calls it at the end of the scope.
|
|
*/
|
|
unlisten(): Promise<void>;
|
|
}
|
|
|
|
/**
|
|
* A pending SQL query. Extends `Promise`, so it can be awaited, and adds
|
|
* methods to control how it runs.
|
|
*/
|
|
interface Query<T> extends Promise<T> {
|
|
/**
|
|
* True while the query is executing
|
|
*/
|
|
active: boolean;
|
|
|
|
/**
|
|
* True if the query has been cancelled
|
|
*/
|
|
cancelled: boolean;
|
|
|
|
/**
|
|
* Cancels the executing query
|
|
*/
|
|
cancel(): Query<T>;
|
|
|
|
/**
|
|
* Executes the query as a simple query. Parameters are not allowed, but
|
|
* the query can contain multiple commands separated by semicolons.
|
|
*/
|
|
simple(): Query<T>;
|
|
|
|
/**
|
|
* Starts executing the query. Queries are lazy: they only run when
|
|
* awaited or executed with this method.
|
|
*/
|
|
execute(): Query<T>;
|
|
|
|
/**
|
|
* Returns rows as arrays of `Buffer` objects instead of objects
|
|
*/
|
|
raw(): Query<T>;
|
|
|
|
/**
|
|
* Returns each row as an array of values, in the same order as the
|
|
* columns in the query
|
|
*/
|
|
values(): Query<T>;
|
|
}
|
|
|
|
/**
|
|
* Callback function type for transaction contexts
|
|
* @param sql Function to execute SQL queries within the transaction
|
|
*/
|
|
type TransactionContextCallback<T> = ContextCallback<T, TransactionSQL>;
|
|
|
|
/**
|
|
* Callback function type for savepoint contexts
|
|
* @param sql Function to execute SQL queries within the savepoint
|
|
*/
|
|
type SavepointContextCallback<T> = ContextCallback<T, SavepointSQL>;
|
|
|
|
/**
|
|
* A parameter or serializable value interpolated into a query.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const helper = sql(users, 'id');
|
|
* await sql`insert into users ${helper}`;
|
|
* ```
|
|
*/
|
|
interface Helper<T> {
|
|
readonly value: T[];
|
|
readonly columns: (keyof T)[];
|
|
}
|
|
}
|
|
|
|
interface SQL extends AsyncDisposable {
|
|
/**
|
|
* Executes a SQL query using template literals
|
|
* @example
|
|
* ```ts
|
|
* const [user] = await sql<Users[]>`select * from users where id = ${1}`;
|
|
* ```
|
|
*/
|
|
<T = any>(strings: TemplateStringsArray, ...values: unknown[]): SQL.Query<T>;
|
|
|
|
/**
|
|
* Executes a SQL query from a string
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const users = await sql<User[]>("SELECT * FROM users");
|
|
* ```
|
|
*/
|
|
<T = any>(string: string): SQL.Query<T>;
|
|
|
|
/**
|
|
* Helper function for inserting an object into a query
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* // Insert an object
|
|
* const result = await sql`insert into users ${sql(users)} returning *`;
|
|
*
|
|
* // Or pick specific columns
|
|
* const result = await sql`insert into users ${sql(users, "id", "name")} returning *`;
|
|
*
|
|
* // Or a single object
|
|
* const result = await sql`insert into users ${sql(user)} returning *`;
|
|
* ```
|
|
*/
|
|
<T extends { [Key in PropertyKey]: unknown }>(obj: T | T[] | readonly T[]): SQL.Helper<T>; // Contributor note: This is the same as the signature below with the exception of the columns and the Pick<T, Keys>
|
|
|
|
/**
|
|
* Helper function for inserting an object into a query, supporting specific columns
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* // Insert an object
|
|
* const result = await sql`insert into users ${sql(users)} returning *`;
|
|
*
|
|
* // Or pick specific columns
|
|
* const result = await sql`insert into users ${sql(users, "id", "name")} returning *`;
|
|
*
|
|
* // Or a single object
|
|
* const result = await sql`insert into users ${sql(user)} returning *`;
|
|
* ```
|
|
*/
|
|
<T extends { [Key in PropertyKey]: unknown }, Keys extends keyof T = keyof T>(
|
|
obj: T | T[] | readonly T[],
|
|
...columns: readonly Keys[]
|
|
): SQL.Helper<Pick<T, Keys>>; // Contributor note: This is the same as the signature above with the exception of this signature tracking keys
|
|
|
|
/**
|
|
* Helper function for inserting any serializable value into a query
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const result = await sql`SELECT * FROM users WHERE id IN ${sql([1, 2, 3])}`;
|
|
* ```
|
|
*/
|
|
// `T & {}` rejects a bare `null`/`undefined` value, which the runtime
|
|
// throws on. An array such as `[null]` stays allowed: it is a valid
|
|
// `WHERE IN` binding and is an object, so it still satisfies `{}`.
|
|
<T>(value: T & {}): SQL.Helper<T>;
|
|
}
|
|
|
|
/**
|
|
* SQL client. Manages a connection pool, queries, and transactions.
|
|
*/
|
|
class SQL {
|
|
/**
|
|
* Creates a new SQL client instance
|
|
*
|
|
* @param connectionString Database connection string or URL
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const sql = new SQL("postgres://localhost:5432/mydb");
|
|
* const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
|
|
* ```
|
|
*/
|
|
constructor(connectionString: string | URL);
|
|
|
|
/**
|
|
* Creates a new SQL client instance with options
|
|
*
|
|
* @param connectionString Database connection string or URL
|
|
* @param options Connection and pool options
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
|
|
* ```
|
|
*/
|
|
constructor(
|
|
connectionString: string | URL,
|
|
options: Bun.__internal.DistributedOmit<SQL.Options, "url" | "filename">,
|
|
);
|
|
|
|
/**
|
|
* Creates a new SQL client instance with options
|
|
*
|
|
* @param options Connection and pool options, including the URL or filename
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
|
|
* ```
|
|
*/
|
|
constructor(options?: SQL.Options);
|
|
|
|
/**
|
|
* Current client options
|
|
*/
|
|
options: Bun.__internal.DistributedMerge<SQL.Options>;
|
|
|
|
/**
|
|
* Commits a distributed transaction, also known as a prepared transaction
|
|
* in PostgreSQL or an XA transaction in MySQL
|
|
*
|
|
* @param name Name of the distributed transaction
|
|
*
|
|
* @throws {Error} If the adapter does not support distributed transactions (e.g., SQLite)
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.commitDistributed("my_distributed_transaction");
|
|
* ```
|
|
*/
|
|
commitDistributed(name: string): Promise<void>;
|
|
|
|
/**
|
|
* Rolls back a distributed transaction, also known as a prepared
|
|
* transaction in PostgreSQL or an XA transaction in MySQL
|
|
*
|
|
* @param name Name of the distributed transaction
|
|
*
|
|
* @throws {Error} If the adapter does not support distributed transactions (e.g., SQLite)
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.rollbackDistributed("my_distributed_transaction");
|
|
* ```
|
|
*/
|
|
rollbackDistributed(name: string): Promise<void>;
|
|
|
|
/** Waits for the database connection to be established
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.connect();
|
|
* ```
|
|
*/
|
|
connect(): Promise<SQL>;
|
|
|
|
/**
|
|
* Closes the database connection. With `timeout: 0` it closes
|
|
* immediately; with no timeout it waits for all queries to finish first.
|
|
*
|
|
* @param options Optional `timeout` in seconds
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.close({ timeout: 1 });
|
|
* ```
|
|
*/
|
|
close(options?: { timeout?: number }): Promise<void>;
|
|
|
|
/**
|
|
* Closes the database connection. Alias of {@link SQL.close}.
|
|
*
|
|
* @param options Optional `timeout` in seconds
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.end({ timeout: 1 });
|
|
* ```
|
|
*/
|
|
end(options?: { timeout?: number }): Promise<void>;
|
|
|
|
/**
|
|
* Flushes any pending operations
|
|
*
|
|
* @throws {Error} If the adapter does not support flushing (e.g., SQLite)
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* sql.flush();
|
|
* ```
|
|
*/
|
|
flush(): void;
|
|
|
|
/**
|
|
* Reserves a connection from the pool and returns a client that wraps
|
|
* that single connection. Use it to run queries on an isolated
|
|
* connection.
|
|
*
|
|
* Calling `reserve()` on a reserved client returns a new reserved
|
|
* connection, not the same one (behavior matches the `postgres` package).
|
|
*
|
|
* @throws {Error} If the adapter does not support connection pooling (e.g., SQLite)
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const reserved = await sql.reserve();
|
|
* await reserved`select * from users`;
|
|
* await reserved.release();
|
|
*
|
|
* // In production, release in a finally block
|
|
* const reserved = await sql.reserve();
|
|
* try {
|
|
* // ... queries
|
|
* } finally {
|
|
* await reserved.release();
|
|
* }
|
|
*
|
|
* // Bun supports Symbol.dispose and Symbol.asyncDispose,
|
|
* // so `using` releases the connection at the end of the scope
|
|
* using reserved = await sql.reserve()
|
|
* await reserved`select * from users`
|
|
* ```
|
|
*/
|
|
reserve(): Promise<ReservedSQL>;
|
|
|
|
/**
|
|
* Creates a SQL array parameter
|
|
* @param values Array values to bind
|
|
* @param typeNameOrTypeID Element type name or type ID; defaults to JSON when omitted
|
|
* @returns The array parameter, ready to interpolate into a query
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const array = sql.array([1, 2, 3], "INT");
|
|
* await sql`CREATE TABLE users_posts (user_id INT, posts_id INT[])`;
|
|
* await sql`INSERT INTO users_posts (user_id, posts_id) VALUES (${user.id}, ${array})`;
|
|
* ```
|
|
*/
|
|
array(values: any[], typeNameOrTypeID?: number | ArrayType): SQLArrayParameter;
|
|
|
|
/**
|
|
* Begins a new transaction.
|
|
*
|
|
* Reserves a connection for the transaction and passes a scoped `sql`
|
|
* instance to the callback. `sql.begin` resolves with the callback's
|
|
* return value. `BEGIN` is sent automatically, and if anything fails,
|
|
* `ROLLBACK` is sent so the connection can be released and execution can
|
|
* continue.
|
|
* @example
|
|
* ```ts
|
|
* const [user, account] = await sql.begin(async sql => {
|
|
* const [user] = await sql`
|
|
* insert into users (
|
|
* name
|
|
* ) values (
|
|
* 'Murray'
|
|
* )
|
|
* returning *
|
|
* `
|
|
* const [account] = await sql`
|
|
* insert into accounts (
|
|
* user_id
|
|
* ) values (
|
|
* ${ user.user_id }
|
|
* )
|
|
* returning *
|
|
* `
|
|
* return [user, account]
|
|
* })
|
|
* ```
|
|
*/
|
|
begin<const T>(fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/**
|
|
* Begins a new transaction with options.
|
|
*
|
|
* Reserves a connection for the transaction and passes a scoped `sql`
|
|
* instance to the callback. `sql.begin` resolves with the callback's
|
|
* return value. `BEGIN` is sent with the given options, and if anything
|
|
* fails, `ROLLBACK` is sent so the connection can be released and
|
|
* execution can continue.
|
|
* @example
|
|
* ```ts
|
|
* const [user, account] = await sql.begin("read write", async sql => {
|
|
* const [user] = await sql`
|
|
* insert into users (
|
|
* name
|
|
* ) values (
|
|
* 'Murray'
|
|
* )
|
|
* returning *
|
|
* `
|
|
* const [account] = await sql`
|
|
* insert into accounts (
|
|
* user_id
|
|
* ) values (
|
|
* ${ user.user_id }
|
|
* )
|
|
* returning *
|
|
* `
|
|
* return [user, account]
|
|
* })
|
|
* ```
|
|
*/
|
|
begin<const T>(options: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/**
|
|
* Begins a new transaction. Alias of {@link begin}.
|
|
*
|
|
* Reserves a connection for the transaction and passes a scoped `sql`
|
|
* instance to the callback. `sql.transaction` resolves with the
|
|
* callback's return value. `BEGIN` is sent automatically, and if
|
|
* anything fails, `ROLLBACK` is sent so the connection can be released
|
|
* and execution can continue.
|
|
* @alias begin
|
|
* @example
|
|
* ```ts
|
|
* const [user, account] = await sql.transaction(async sql => {
|
|
* const [user] = await sql`
|
|
* insert into users (
|
|
* name
|
|
* ) values (
|
|
* 'Murray'
|
|
* )
|
|
* returning *
|
|
* `
|
|
* const [account] = await sql`
|
|
* insert into accounts (
|
|
* user_id
|
|
* ) values (
|
|
* ${ user.user_id }
|
|
* )
|
|
* returning *
|
|
* `
|
|
* return [user, account]
|
|
* })
|
|
* ```
|
|
*/
|
|
transaction<const T>(fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/**
|
|
* Begins a new transaction with options. Alias of {@link begin}.
|
|
*
|
|
* Reserves a connection for the transaction and passes a scoped `sql`
|
|
* instance to the callback. `sql.transaction` resolves with the
|
|
* callback's return value. `BEGIN` is sent with the given options, and
|
|
* if anything fails, `ROLLBACK` is sent so the connection can be
|
|
* released and execution can continue.
|
|
*
|
|
* @alias {@link begin}
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const [user, account] = await sql.transaction("read write", async sql => {
|
|
* const [user] = await sql`
|
|
* insert into users (
|
|
* name
|
|
* ) values (
|
|
* 'Murray'
|
|
* )
|
|
* returning *
|
|
* `
|
|
* const [account] = await sql`
|
|
* insert into accounts (
|
|
* user_id
|
|
* ) values (
|
|
* ${ user.user_id }
|
|
* )
|
|
* returning *
|
|
* `
|
|
* return [user, account]
|
|
* });
|
|
* ```
|
|
*/
|
|
transaction<const T>(options: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/**
|
|
* Begins a distributed transaction, also known as Two-Phase Commit. In
|
|
* phase 1 the coordinator prepares each node, making sure its data is
|
|
* written and ready to commit; in phase 2 the nodes commit or roll back
|
|
* based on the coordinator's decision, ensuring durability and releasing
|
|
* locks.
|
|
*
|
|
* `beginDistributed` rolls back automatically if an exception is not
|
|
* caught; otherwise you commit or roll back later with
|
|
* {@link commitDistributed} or {@link rollbackDistributed}.
|
|
*
|
|
* In PostgreSQL and MySQL, distributed transactions persist beyond the
|
|
* original session, so privileged users or coordinators can commit or
|
|
* roll them back later, which supports recovery and administrative
|
|
* tasks. PostgreSQL implements them with `PREPARE TRANSACTION`; MySQL
|
|
* uses XA Transactions. MSSQL also supports distributed/XA transactions,
|
|
* but ties them to the original session, the DTC coordinator, and the
|
|
* specific connection: they are committed or rolled back under the same
|
|
* rules as regular transactions, with no manual intervention from other
|
|
* sessions, and are used to coordinate transactions across Linked
|
|
* Servers.
|
|
*
|
|
* @throws {Error} If the adapter does not support distributed transactions (e.g., SQLite)
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.beginDistributed("numbers", async sql => {
|
|
* await sql`create table if not exists numbers (a int)`;
|
|
* await sql`insert into numbers values(1)`;
|
|
* });
|
|
* // later you can call
|
|
* await sql.commitDistributed("numbers");
|
|
* // or await sql.rollbackDistributed("numbers");
|
|
* ```
|
|
*/
|
|
beginDistributed<const T>(
|
|
name: string,
|
|
fn: SQL.TransactionContextCallback<T>,
|
|
): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/** Begins a distributed transaction. Alias of {@link beginDistributed}.
|
|
* @alias {@link beginDistributed}
|
|
*/
|
|
distributed<const T>(name: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
|
|
|
|
/**
|
|
* Executes any query string as-is. This can lead to SQL injection if the
|
|
* string contains untrusted input.
|
|
*
|
|
* `sql.unsafe` can be nested inside a safe `sql` expression, for example
|
|
* when only part of the query is unsafe.
|
|
*
|
|
* With the SQLite adapter, `values` may also be an object of named
|
|
* parameters (`:name`, `$name`, or `@name` placeholders). Object keys
|
|
* keep the prefix unless the connection sets `strict: true`.
|
|
* @example
|
|
* ```ts
|
|
* const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)
|
|
* const row = await sql.unsafe("select * from users where id = :id", { ":id": 1 })
|
|
* ```
|
|
*/
|
|
unsafe<T = any>(string: string, values?: any[] | Record<string, any>): SQL.Query<T>;
|
|
|
|
/**
|
|
* Reads a file and runs its contents as a query.
|
|
* Pass `values` if the file uses positional parameters (`$1`, `$2`, ...).
|
|
* With the SQLite adapter, `values` may also be an object of named
|
|
* parameters (`:name`, `$name`, or `@name` placeholders); keys keep the
|
|
* prefix unless the connection sets `strict: true`.
|
|
* @example
|
|
* ```ts
|
|
* const result = await sql.file("query.sql", [1, 2, 3]);
|
|
* ```
|
|
*/
|
|
file<T = any>(filename: string, values?: any[] | Record<string, any>): SQL.Query<T>;
|
|
|
|
/**
|
|
* Subscribe to a PostgreSQL `LISTEN` channel. Resolves once the server has
|
|
* acknowledged the subscription, with a handle that removes it again.
|
|
*
|
|
* Every call is its own registration: several on one channel share a
|
|
* single server-side subscription and each receives every notification.
|
|
* All of them share one dedicated connection, opened by the first
|
|
* `listen()` and closed when the last registration is removed. If it
|
|
* drops, it is reconnected with exponential backoff and every channel is
|
|
* re-subscribed; `onlisten` runs again each time.
|
|
*
|
|
* A throwing `onnotify` or `onlisten` is reported as an uncaught exception.
|
|
*
|
|
* @param channel - Channel name, quoted for you; at most 63 bytes, the
|
|
* PostgreSQL identifier limit
|
|
* @param onnotify - Receives each notification's payload
|
|
* @param onlisten - Runs once the `LISTEN` is acknowledged, initially and
|
|
* after every reconnect
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const subscription = await sql.listen("events", payload => console.log(payload));
|
|
* await sql.notify("events", "hello");
|
|
* await subscription.unlisten();
|
|
* ```
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await using subscription = await sql.listen("events", handle);
|
|
* ```
|
|
*/
|
|
listen(
|
|
channel: string,
|
|
onnotify: (payload: string) => void,
|
|
onlisten?: () => void,
|
|
): Promise<SQL.ListenSubscription>;
|
|
|
|
/**
|
|
* Send a PostgreSQL `NOTIFY` via `pg_notify`. Runs as a normal query on
|
|
* this handle, so on a `sql.begin()` transaction it is delivered on commit
|
|
* and discarded on rollback. Omitting `payload` sends an empty one, like a
|
|
* bare `NOTIFY channel`.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* await sql.notify("events", JSON.stringify({ id: 1 }));
|
|
* await sql.notify("cache-invalidated");
|
|
* ```
|
|
*/
|
|
notify(channel: string, payload?: string): Promise<void>;
|
|
}
|
|
|
|
/**
|
|
* The default SQL client, configured from environment variables such as
|
|
* `DATABASE_URL`
|
|
*/
|
|
const sql: SQL;
|
|
|
|
/**
|
|
* SQL client for PostgreSQL
|
|
*
|
|
* @deprecated Prefer {@link Bun.sql}
|
|
*/
|
|
const postgres: SQL;
|
|
|
|
/**
|
|
* The client passed to {@link TransactionSQL.savepoint} callbacks; queries
|
|
* run within that savepoint
|
|
*/
|
|
interface SavepointSQL extends SQL {}
|
|
}
|