mysql.d.ts

// Type definitions for node-mysql
// Project: https://github.com/felixge/node-mysql
// Definitions by: William Johnston <https://github.com/wjohnsto>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

///<reference path='../node/node.d.ts' />

declare module "mysql" {
	import stream = require("stream");

	function createConnection(connectionUri: string): IConnection;
	function createConnection(config: IConnectionConfig): IConnection;
	function createPool(config: IPoolConfig): IPool;
	function createPoolCluster(config?: IPoolClusterConfig): IPoolCluster;
	function escape(value: any): string;
	function format(sql: string): string;
	function format(sql: string, values: Array<any>): string;
	function format(sql: string, values: any): string;

	interface IMySql {
		createConnection(connectionUri: string): IConnection;
		createConnection(config: IConnectionConfig): IConnection;
		createPool(config: IPoolConfig): IPool;
		createPoolCluster(config?: IPoolClusterConfig): IPoolCluster;
		escape(value: any): string;
		format(sql: string): string;
		format(sql: string, values: Array<any>): string;
		format(sql: string, values: any): string;
	}

    interface IConnectionStatic {
        createQuery(sql: string): IQuery;
        createQuery(sql: string, callback: (err: IError, ...args: any[]) => void): IQuery;
        createQuery(sql: string, values: Array<any>): IQuery;
        createQuery(sql: string, values: Array<any>, callback: (err: IError, ...args: any[]) => void): IQuery;
    }

    interface IConnection {
        config: IConnectionConfig;

        threadId: number;

        beginTransaction(callback: (err: IError) => void): void;

        connect(): void;
        connect(callback: (err: IError, ...args: any[]) => void): void;
        connect(options: any, callback?: (err: IError, ...args: any[]) => void): void;

        commit(callback: (err: IError) => void): void;

        changeUser(options: IConnectionOptions): void;
        changeUser(options: IConnectionOptions, callback: (err: IError) => void): void;

        query: IQueryFunction;

        end(): void;
        end(callback: (err: IError, ...args: any[]) => void): void;
        end(options: any, callback: (err: IError, ...args: any[]) => void): void;

        destroy(): void;

        pause(): void;

        release(): void;
        resume(): void;

        escape(value: any): string;

        escapeId(value: string): string;
        escapeId(values: Array<string>): string;

        format(sql: string): string;
        format(sql: string, values: Array<any>): string;
        format(sql: string, values: any): string;

        on(ev: string, callback: (...args: any[]) => void): IConnection;
        on(ev: 'error', callback: (err: IError) => void): IConnection;

        rollback(callback: () => void): void;
    }

    interface IPool {
        config: IPoolConfig;

        getConnection(callback: (err: IError, connection: IConnection) => void): void;

        query: IQueryFunction;

        end(): void;
        end(callback: (err: IError, ...args: any[]) => void): void;

        on(ev: string, callback: (...args: any[]) => void): IPool;
        on(ev: 'connection', callback: (connection: IConnection) => void): IPool;
        on(ev: 'error', callback: (err: IError) => void): IPool;
    }

    interface IPoolCluster {
        config: IPoolClusterConfig;

        add(config: IPoolConfig): void;
        add(group: string, config: IPoolConfig): void;

        end(): void;

        getConnection(callback: (err: IError, connection: IConnection) => void): void;
        getConnection(group: string, callback: (err: IError, connection: IConnection) => void): void;
        getConnection(group: string, selector: string, callback: (err: IError, connection: IConnection) => void): void;

        of(pattern: string): IPool;
        of(pattern: string, selector: string): IPool;

        on(ev: string, callback: (...args: any[]) => void): IPoolCluster;
        on(ev: 'remove', callback: (nodeId: number) => void): IPoolCluster;
        on(ev: 'connection', callback: (connection: IConnection) => void): IPoolCluster;
        on(ev: 'error', callback: (err: IError) => void): IPoolCluster;
    }

    interface IQuery {
        /**
         * The SQL for a constructed query
         */
        sql: string;

        /**
         * Emits a query packet to start the query
         */
        start(): void;

        /**
         * Determines the packet class to use given the first byte of the packet.
         * 
         * @param firstByte The first byte of the packet
         * @param parser The packet parser
         */
        determinePacket(firstByte: number, parser: any): any;

        /**
         * Creates a Readable stream with the given options
         * 
         * @param options The options for the stream.
         */
        stream(options: IStreamOptions): stream.Readable;

        /**
         * Pipes a stream downstream, providing automatic pause/resume based on the 
         * options sent to the stream.
         * 
         * @param options The options for the stream.
         */
        pipe(callback: (...args: any[]) => void): IQuery;

        on(ev: string, callback: (...args: any[]) => void): IQuery;
        on(ev: 'error', callback: (err: IError) => void): IQuery;
        on(ev: 'fields', callback: (fields: any, index: number) => void): IQuery;
        on(ev: 'result', callback: (row: any, index: number) => void): IQuery;
        on(ev: 'end', callback: () => void): IQuery;
    }

    interface IQueryFunction {
        (sql: string): IQuery;
        (sql: string, callback: (err: IError, ...args: any[]) => void): IQuery;
        (sql: string, values: Array<any>): IQuery;
        (sql: string, values: Array<any>, callback: (err: IError, ...args: any[]) => void): IQuery;
        (sql: string, values: any): IQuery;
        (sql: string, values: any, callback: (err: IError, ...args: any[]) => void): IQuery;
        (options: IQueryOptions): IQuery;
        (options: IQueryOptions, callback: (err: IError, ...args: any[]) => void): IQuery;
        (options: IQueryOptions, values: Array<any>): IQuery;
        (options: IQueryOptions, values: Array<any>, callback: (err: IError, ...args: any[]) => void): IQuery;
        (options: IQueryOptions, values: any): IQuery;
        (options: IQueryOptions, values: any, callback: (err: IError, ...args: any[]) => void): IQuery;
    }

    interface IQueryOptions {
        /**
         * The SQL for the query
         */
        sql: string;

        /**
         * Every operation takes an optional inactivity timeout option. This allows you to specify appropriate timeouts for 
         * operations. It is important to note that these timeouts are not part of the MySQL protocol, and rather timeout 
         * operations through the client. This means that when a timeout is reached, the connection it occurred on will be 
         * destroyed and no further operations can be performed.
         */
        timeout?: number;

        /**
         * Either a boolean or string. If true, tables will be nested objects. If string (e.g. '_'), tables will be 
         * nested as tableName_fieldName
         */
        nestTables?: any;

        /**
         * Determines if column values should be converted to native JavaScript types. It is not recommended (and may go away / change in the future) 
         * to disable type casting, but you can currently do so on either the connection or query level. (Default: true)
         * 
         * You can also specify a function (field: any, next: () => void) => {} to do the type casting yourself.
         * 
         * WARNING: YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once.
         * 
         * field.string()
         * field.buffer()
         * field.geometry()
         * 
         * are aliases for
         * 
         * parser.parseLengthCodedString()
         * parser.parseLengthCodedBuffer()
         * parser.parseGeometryValue()
         * 
         * You can find which field function you need to use by looking at: RowDataPacket.prototype._typeCast
         */
        typeCast?: any;
    }

    interface IStreamOptions {
        /**
         * Sets the max buffer size in objects of a stream
         */
        highWaterMark?: number;

        /**
         * The object mode of the stream (Default: true)
         */
        objectMode?: any;
    }

    interface IConnectionOptions {
        /**
         * The MySQL user to authenticate as
         */
        user?: string;

        /**
         * The password of that MySQL user
         */
        password?: string;

        /**
         * Name of the database to use for this connection
         */
        database?: string;

        /**
         * The charset for the connection. This is called "collation" in the SQL-level of MySQL (like utf8_general_ci). 
         * If a SQL-level charset is specified (like utf8mb4) then the default collation for that charset is used. 
         * (Default: 'UTF8_GENERAL_CI')
         */
        charset?: string;
    }

    interface IConnectionConfig extends IConnectionOptions {
        /**
         * The hostname of the database you are connecting to. (Default: localhost)
         */
        host?: string;

        /**
         * The port number to connect to. (Default: 3306)
         */
        port?: number;

        /**
         * The source IP address to use for TCP connection
         */
        localAddress?: string;

        /**
         * The path to a unix domain socket to connect to. When used host and port are ignored
         */
        socketPath?: string;

        /**
         * The timezone used to store local dates. (Default: 'local')
         */
        timezone?: string;

        /**
         * The milliseconds before a timeout occurs during the initial connection to the MySQL server. (Default: 10 seconds)
         */
        connectTimeout?: number;

        /**
         * Stringify objects instead of converting to values. (Default: 'false')
         */
        stringifyObjects?: boolean;

        /**
         * Allow connecting to MySQL instances that ask for the old (insecure) authentication method. (Default: false)
         */
        insecureAuth?: boolean;

        /**
         * Determines if column values should be converted to native JavaScript types. It is not recommended (and may go away / change in the future) 
         * to disable type casting, but you can currently do so on either the connection or query level. (Default: true)
         * 
         * You can also specify a function (field: any, next: () => void) => {} to do the type casting yourself.
         * 
         * WARNING: YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once.
         * 
         * field.string()
         * field.buffer()
         * field.geometry()
         * 
         * are aliases for
         * 
         * parser.parseLengthCodedString()
         * parser.parseLengthCodedBuffer()
         * parser.parseGeometryValue()
         * 
         * You can find which field function you need to use by looking at: RowDataPacket.prototype._typeCast
         */
        typeCast?: any;

        /**
         * A custom query format function
         */
        queryFormat?: (query: string, values: any) => void;

        /**
         * When dealing with big numbers (BIGINT and DECIMAL columns) in the database, you should enable this option 
         * (Default: false)
         */
        supportBigNumbers?: boolean;

        /**
         * Enabling both supportBigNumbers and bigNumberStrings forces big numbers (BIGINT and DECIMAL columns) to be 
         * always returned as JavaScript String objects (Default: false). Enabling supportBigNumbers but leaving 
         * bigNumberStrings disabled will return big numbers as String objects only when they cannot be accurately 
         * represented with [JavaScript Number objects] (http://ecma262-5.com/ELS5_HTML.htm#Section_8.5) 
         * (which happens when they exceed the [-2^53, +2^53] range), otherwise they will be returned as Number objects. 
         * This option is ignored if supportBigNumbers is disabled.
         */
        bigNumberStrings?: boolean;

        /**
         * Force date types (TIMESTAMP, DATETIME, DATE) to be returned as strings rather then inflated into JavaScript Date 
         * objects. (Default: false)
         */
        dateStrings?: boolean;

        /**
         * This will print all incoming and outgoing packets on stdout. 
         * You can also restrict debugging to packet types by passing an array of types (strings) to debug;
         * 
         * (Default: false)
         */
        debug?: any;

        /**
         * Generates stack traces on Error to include call site of library entrance ("long stack traces"). Slight 
         * performance penalty for most calls. (Default: true)
         */
        trace?: boolean;

        /**
         * Allow multiple mysql statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
         */
        multipleStatements?: boolean;

        /**
         * List of connection flags to use other than the default ones. It is also possible to blacklist default ones
         */
        flags?: Array<string>;

        /**
         * object with ssl parameters or a string containing name of ssl profile
         */
        ssl?: any;
    }

    interface IPoolConfig extends IConnectionConfig {
        /**
         * The milliseconds before a timeout occurs during the connection acquisition. This is slightly different from connectTimeout, 
         * because acquiring a pool connection does not always involve making a connection. (Default: 10 seconds)
         */
        acquireTimeout?: number;

        /**
         * Determines the pool's action when no connections are available and the limit has been reached. If true, the pool will queue 
         * the connection request and call it when one becomes available. If false, the pool will immediately call back with an error. 
         * (Default: true)
         */
        waitForConnections?: boolean;

        /**
         * The maximum number of connections to create at once. (Default: 10)
         */
        connectionLimit?: number;

        /**
         * The maximum number of connection requests the pool will queue before returning an error from getConnection. If set to 0, there 
         * is no limit to the number of queued connection requests. (Default: 0)
         */
        queueLimit?: number;
    }

    interface IPoolClusterConfig {
        /**
         * If true, PoolCluster will attempt to reconnect when connection fails. (Default: true)
         */
        canRetry?: boolean;

        /**
         * If connection fails, node's errorCount increases. When errorCount is greater than removeNodeErrorCount, 
         * remove a node in the PoolCluster. (Default: 5)
         */
        removeNodeErrorCount?: number;

        /**
         * If connection fails, specifies the number of milliseconds before another connection attempt will be made.
         * If set to 0, then node will be removed instead and never re-used. (Default: 0)
         */
        restoreNodeTimeout?: number;

        /**
         * The default selector. (Default: RR)
         * RR: Select one alternately. (Round-Robin)
         * RANDOM: Select the node by random function.
         * ORDER: Select the first node available unconditionally.
         */
        defaultSelector?: string;
    }

    interface ISslCredentials {
        /**
         * A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
         */
        pfx?: string;

        /**
         * A string holding the PEM encoded private key
         */
        key?: string;
        
        /**
         * A string of passphrase for the private key or pfx
         */
        passphrase?: string;
        
        /**
         * A string holding the PEM encoded certificate
         */
        cert?: string;
        
        /**
         * Either a string or list of strings of PEM encoded CA certificates to trust.
         */
        ca?: Array<string>;
        
        /**
         * Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
         */
        crl?: Array<string>;
        
        /**
         * A string describing the ciphers to use or exclude
         */
        ciphers?: string;
    }

    interface IError extends Error {
        /**
         * Either a MySQL server error (e.g. 'ER_ACCESS_DENIED_ERROR'), 
         * a node.js error (e.g. 'ECONNREFUSED') or an internal error 
         * (e.g. 'PROTOCOL_CONNECTION_LOST').
         */
        code: string;

        /**
         * The error number for the error code
         */
        errno: number;

        /**
         * The sql state marker
         */
        sqlStateMarker?: string;

        /**
         * The sql state
         */
        sqlState?: string;

        /**
         * The field count
         */
        fieldCount?: number;

        /**
         * The stack trace for the error
         */
        stack?: string;

        /**
         * Boolean, indicating if this error is terminal to the connection object.
         */
        fatal: boolean;
    }
}