SQL.constructor

• class MySQLError

  • cause?: unknown

    The cause of the error.

  • readonly code: string
  • readonly errno: undefined | number
  • message: string
  • name: string
  • readonly sqlState: undefined | string
  • stack?: string
  • static stackTraceLimit: number

    The maximum number of stack frames to capture.

  • static captureStackTrace(

    targetObject: object,

    constructorOpt?: Function

    ): void;

    Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

    const myObject = {};
    Error.captureStackTrace(myObject);
    myObject.stack;  // Similar to `new Error().stack`
    

    The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

    The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

    The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

    function a() {
      b();
    }
    
    function b() {
      c();
    }
    
    function c() {
      // Create an error without stack trace to avoid calculating the stack trace twice.
      const { stackTraceLimit } = Error;
      Error.stackTraceLimit = 0;
      const error = new Error();
      Error.stackTraceLimit = stackTraceLimit;
    
      // Capture the stack trace above function b
      Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
      throw error;
    }
    
    a();
    
  • 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: undefined | string
  • readonly constraint: undefined | string
  • readonly dataType: undefined | string
  • readonly detail: undefined | string
  • readonly errno: undefined | string
  • readonly file: undefined | string
  • readonly hint: undefined | string
  • readonly internalPosition: undefined | string
  • readonly internalQuery: undefined | string
  • readonly line: undefined | string
  • message: string
  • name: string
  • readonly position: undefined | string
  • readonly routine: undefined | string
  • readonly schema: undefined | string
  • readonly severity: undefined | string
  • stack?: string
  • readonly table: undefined | string
  • readonly where: undefined | string
  • static stackTraceLimit: number

    The maximum number of stack frames to capture.

  • static captureStackTrace(

    targetObject: object,

    constructorOpt?: Function

    ): void;

    Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

    const myObject = {};
    Error.captureStackTrace(myObject);
    myObject.stack;  // Similar to `new Error().stack`
    

    The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

    The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

    The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

    function a() {
      b();
    }
    
    function b() {
      c();
    }
    
    function c() {
      // Create an error without stack trace to avoid calculating the stack trace twice.
      const { stackTraceLimit } = Error;
      Error.stackTraceLimit = 0;
      const error = new Error();
      Error.stackTraceLimit = stackTraceLimit;
    
      // Capture the stack trace above function b
      Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
      throw error;
    }
    
    a();
    
  • 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 maximum number of stack frames to capture.

  • static captureStackTrace(

    targetObject: object,

    constructorOpt?: Function

    ): void;

    Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

    const myObject = {};
    Error.captureStackTrace(myObject);
    myObject.stack;  // Similar to `new Error().stack`
    

    The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

    The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

    The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

    function a() {
      b();
    }
    
    function b() {
      c();
    }
    
    function c() {
      // Create an error without stack trace to avoid calculating the stack trace twice.
      const { stackTraceLimit } = Error;
      Error.stackTraceLimit = 0;
      const error = new Error();
      Error.stackTraceLimit = stackTraceLimit;
    
      // Capture the stack trace above function b
      Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
      throw error;
    }
    
    a();
    
  • 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 maximum number of stack frames to capture.

  • static captureStackTrace(

    targetObject: object,

    constructorOpt?: Function

    ): void;

    Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

    const myObject = {};
    Error.captureStackTrace(myObject);
    myObject.stack;  // Similar to `new Error().stack`
    

    The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

    The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

    The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

    function a() {
      b();
    }
    
    function b() {
      c();
    }
    
    function c() {
      // Create an error without stack trace to avoid calculating the stack trace twice.
      const { stackTraceLimit } = Error;
      Error.stackTraceLimit = 0;
      const error = new Error();
      Error.stackTraceLimit = stackTraceLimit;
    
      // Capture the stack trace above function b
      Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
      throw error;
    }
    
    a();
    
  • 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

  • host?: 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

  • ssl?: boolean | TLSOptions

    Whether to use TLS/SSL for the connection (alias for tls)

  • tls?: boolean | 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

interface SQLiteOptions

• 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.

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

• host?: 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

• ssl?: boolean | TLSOptions

  Whether to use TLS/SSL for the connection (alias for tls)

• tls?: boolean | 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