method

SQL.connect

Waits for the database connection to be established

await sql.connect();

Referenced types

namespace SQL

class MySQLError
- cause?: unknown
  The cause of the error.
- readonly code: string
- readonly errno?: number
- message: string
- name: string
- readonly sqlState?: string
- stack?: string
- static stackTraceLimit: number
  The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).
  The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.
  If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
- static captureStackTrace(
  targetObject: object,
  constructorOpt?: Function
  ): void;
  Create .stack property on a target object
- static isError(
  value: unknown
  ): value is Error;
  Check if a value is an instance of Error
  @param value
  The value to check
  @returns
  True if the value is an instance of Error, false otherwise
- static prepareStackTrace(
  err: Error,
  stackTraces: CallSite[]
  ): any;
class PostgresError
- cause?: unknown
  The cause of the error.
- readonly code: string
- readonly column?: string
- readonly constraint?: string
- readonly dataType?: string
- readonly detail?: string
- readonly errno?: string
- readonly file?: string
- readonly hint?: string
- readonly internalPosition?: string
- readonly internalQuery?: string
- readonly line?: string
- message: string
- name: string
- readonly position?: string
- readonly routine?: string
- readonly schema?: string
- readonly severity?: string
- stack?: string
- readonly table?: string
- readonly where?: string
- static stackTraceLimit: number
  The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).
  The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.
  If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
- static captureStackTrace(
  targetObject: object,
  constructorOpt?: Function
  ): void;
  Create .stack property on a target object
- static isError(
  value: unknown
  ): value is Error;
  Check if a value is an instance of Error
  @param value
  The value to check
  @returns
  True if the value is an instance of Error, false otherwise
- static prepareStackTrace(
  err: Error,
  stackTraces: CallSite[]
  ): any;
class SQLError
- cause?: unknown
  The cause of the error.
- message: string
- name: string
- stack?: string
- static stackTraceLimit: number
  The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).
  The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.
  If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
- static captureStackTrace(
  targetObject: object,
  constructorOpt?: Function
  ): void;
  Create .stack property on a target object
- static isError(
  value: unknown
  ): value is Error;
  Check if a value is an instance of Error
  @param value
  The value to check
  @returns
  True if the value is an instance of Error, false otherwise
- static prepareStackTrace(
  err: Error,
  stackTraces: CallSite[]
  ): any;
class SQLiteError
- readonly byteOffset?: number
- cause?: unknown
  The cause of the error.
- readonly code: string
- readonly errno: number
- message: string
- name: string
- stack?: string
- static stackTraceLimit: number
  The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).
  The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.
  If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
- static captureStackTrace(
  targetObject: object,
  constructorOpt?: Function
  ): void;
  Create .stack property on a target object
- static isError(
  value: unknown
  ): value is Error;
  Check if a value is an instance of Error
  @param value
  The value to check
  @returns
  True if the value is an instance of Error, false otherwise
- static prepareStackTrace(
  err: Error,
  stackTraces: CallSite[]
  ): any;
interface Helper<T>
SQL.Helper represents a parameter or serializable value inside of a query.
const helper = sql(users, 'id'); await sql`insert into users ${helper}`;
- readonly columns: keyof T[]
- readonly value: T[]
interface PostgresOrMySQLOptions
- adapter?: 'postgres' | 'mysql' | 'mariadb'
  Database adapter/driver to use
- bigint?: boolean
  By default values outside i32 range are returned as strings. If this is true, values outside i32 range are returned as BigInts.
- connection?: Record<string, string | number | boolean>
  Postgres client runtime configuration options
- connectionTimeout?: number
  Maximum time in seconds to wait when establishing a connection
- database?: string
  Name of the database to connect to
- hostname?: string
  Database server hostname
- idleTimeout?: number
  Maximum time in seconds to wait for connection to become available
- max?: number
  Maximum number of connections in the pool
- maxLifetime?: number
  Maximum lifetime in seconds of a connection
- onclose?: (err: null | Error) => void
  Callback executed when a connection is closed Receives the closing Error or null.
- onconnect?: (err: null | Error) => void
  Callback executed when a connection attempt completes Receives an Error on failure, or null on success.
- password?: string | () => MaybePromise<string>
  Database password for authentication
- path?: string
  Unix domain socket path for connection
- port?: string | number
  Database server port number
- prepare?: boolean
  Automatic creation of prepared statements
- tls?: boolean | BunFile | TLSOptions
  Whether to use TLS/SSL for the connection
- url?: string | URL
  Connection URL (can be string or URL object)
- username?: string
  Database user for authentication
interface Query<T>
Represents a SQL query that can be executed, with additional control methods Extends Promise to allow for async/await usage
- readonly [Symbol.toStringTag]: string
- active: boolean
  Indicates if the query is currently executing
- cancelled: boolean
  Indicates if the query has been cancelled
- cancel(): Query<T>;
  Cancels the executing query
- catch<TResult = never>(
  onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
  ): Promise<T | TResult>;
  Attaches a callback for only the rejection of the Promise.
  @param onrejected
  The callback to execute when the Promise is rejected.
  @returns
  A Promise for the completion of the callback.
- execute(): Query<T>;
  Executes the query
- finally(
  onfinally?: null | () => void
  ): Promise<T>;
  Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.
  @param onfinally
  The callback to execute when the Promise is settled (fulfilled or rejected).
  @returns
  A Promise for the completion of the callback.
- raw(): Query<T>;
  Returns the raw query result
- simple(): Query<T>;
  Executes the query as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons
- then<TResult1 = T, TResult2 = never>(
  onfulfilled?: null | (value: T) => TResult1 | PromiseLike<TResult1>,
  onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
  ): Promise<TResult1 | TResult2>;
  Attaches callbacks for the resolution and/or rejection of the Promise.
  @param onfulfilled
  The callback to execute when the Promise is resolved.
  @param onrejected
  The callback to execute when the Promise is rejected.
  @returns
  A Promise for the completion of which ever callback is executed.
- values(): Query<T>;
  Returns only the values from the query result
interface SQLiteOptions
Options for Database
- adapter?: 'sqlite'
- create?: boolean
  Allow creating a new database
  Equivalent to constants.SQLITE_OPEN_CREATE
- filename?: string & {} | URL | ':memory:'
  Specify the path to the database file
  Examples:
  sqlite://:memory:
  sqlite://./path/to/database.db
  sqlite:///Users/bun/projects/my-app/database.db
  ./dev.db
  :memory:
- onclose?: (err: null | Error) => void
  Callback executed when a connection is closed (SQLite) Receives the closing Error or null.
- onconnect?: (err: null | Error) => void
  Callback executed when a connection attempt completes (SQLite) Receives an Error on failure, or null on success.
- readonly?: boolean
  Open the database as read-only (no write operations, no create).
  Equivalent to constants.SQLITE_OPEN_READONLY
- readwrite?: boolean
  Open the database as read-write
  Equivalent to constants.SQLITE_OPEN_READWRITE
- safeIntegers?: boolean
  When set to true, integers are returned as bigint types.
  When set to false, integers are returned as number types and truncated to 52 bits.
- strict?: boolean
  When set to false or undefined:
  Queries missing bound parameters will NOT throw an error
  Bound named parameters in JavaScript need to exactly match the SQL query.
  const db = new Database(":memory:", { strict: false }); db.run("INSERT INTO foo (name) VALUES ($name)", { $name: "foo" });
  When set to true:
  Queries missing bound parameters will throw an error
  Bound named parameters in JavaScript no longer need to be $, :, or @. The SQL query will remain prefixed.
type AwaitPromisesArray<T extends PromiseLike<any>[]> = { [K in keyof T]: Awaited<T[K]> }
type ContextCallback<T, SQL> = (sql: SQL) => Bun.MaybePromise<T>
type ContextCallbackResult<T> = T extends PromiseLike<any>[] ? AwaitPromisesArray<T> : Awaited<T>
type Options = SQLiteOptions | PostgresOrMySQLOptions
Configuration options for SQL client connection and behavior
const config: Bun.SQL.Options = { host: 'localhost', port: 5432, user: 'dbuser', password: 'secretpass', database: 'myapp', idleTimeout: 30, max: 20, onconnect: (client) => { console.log('Connected to database'); } };
type SavepointContextCallback<T> = ContextCallback<T, SavepointSQL>
Callback function type for savepoint contexts
type TransactionContextCallback<T> = ContextCallback<T, TransactionSQL>
Callback function type for transaction contexts

SQL.connect

Referenced types

namespace SQL

class MySQLError

class PostgresError

class SQLError

class SQLiteError

interface Helper<T>

interface PostgresOrMySQLOptions

interface Query<T>

interface SQLiteOptions