Skip to main content
Version: 0.17

Class: BigQueryConnector

Defined in: src/connectors/bigquery.ts:48

Secure BigQuery connector

Connects to Google BigQuery using Application Default Credentials or a service-account key. The database field in the config is the GCP project ID.

Features:

  • SQL injection prevention
  • Credential validation
  • Read-only query patterns
  • Connection timeouts
  • Secure error handling

Example​

import { BigQueryConnector } from '@freshguard/freshguard-core';

const connector = new BigQueryConnector({
  host: 'bigquery.googleapis.com', port: 443,
  database: 'my-gcp-project',
  username: 'service-account@project.iam.gserviceaccount.com',
  password: process.env.BQ_KEY!,
});

Extends​

  • BaseConnector

Constructors​

Constructor​

new BigQueryConnector(config, securityConfig?): BigQueryConnector

Defined in: src/connectors/bigquery.ts:64

Parameters​

config​

ConnectorConfig

Connection config; database is the GCP project ID. Pass options.location (e.g. 'EU', 'us-central1') to target a specific BigQuery region. When omitted, the location is auto-detected from the first accessible dataset; if no datasets exist the default 'US' is used for backward compatibility.

securityConfig?​

Partial<SecurityConfig>

Optional overrides for query timeouts, max rows, and blocked keywords

Returns​

BigQueryConnector

Overrides​

BaseConnector.constructor

Properties​

config​

protected config: ConnectorConfig

Defined in: src/connectors/base-connector.ts:63

Inherited from​

BaseConnector.config

connectionTimeout​

protected readonly connectionTimeout: number

Defined in: src/connectors/base-connector.ts:49

Inherited from​

BaseConnector.connectionTimeout

enableDetailedLogging​

protected readonly enableDetailedLogging: boolean

Defined in: src/connectors/base-connector.ts:57

Inherited from​

BaseConnector.enableDetailedLogging

enableQueryAnalysis​

protected readonly enableQueryAnalysis: boolean

Defined in: src/connectors/base-connector.ts:58

Inherited from​

BaseConnector.enableQueryAnalysis

logger​

protected readonly logger: StructuredLogger

Defined in: src/connectors/base-connector.ts:53

Inherited from​

BaseConnector.logger

maxRows​

protected readonly maxRows: number

Defined in: src/connectors/base-connector.ts:51

Inherited from​

BaseConnector.maxRows

metrics​

protected readonly metrics: MetricsCollector

Defined in: src/connectors/base-connector.ts:54

Inherited from​

BaseConnector.metrics

queryAnalyzer​

protected readonly queryAnalyzer: QueryComplexityAnalyzer

Defined in: src/connectors/base-connector.ts:55

Inherited from​

BaseConnector.queryAnalyzer

queryTimeout​

protected readonly queryTimeout: number

Defined in: src/connectors/base-connector.ts:50

Inherited from​

BaseConnector.queryTimeout

requireSSL​

protected readonly requireSSL: boolean

Defined in: src/connectors/base-connector.ts:52

Inherited from​

BaseConnector.requireSSL

schemaCache​

protected readonly schemaCache: SchemaCache

Defined in: src/connectors/base-connector.ts:56

Inherited from​

BaseConnector.schemaCache

Methods​

cleanup()​

protected cleanup(): void

Defined in: src/connectors/base-connector.ts:806

Cleanup resources (should be called by subclasses in their close method)

Returns​

void

Inherited from​

BaseConnector.cleanup

clearSchemaCache()​

protected clearSchemaCache(): void

Defined in: src/connectors/base-connector.ts:792

Clear schema cache for testing or maintenance

Returns​

void

Inherited from​

BaseConnector.clearSchemaCache

close()​

close(): Promise<void>

Defined in: src/connectors/bigquery.ts:547

Close the BigQuery connection

Returns​

Promise<void>

Overrides​

BaseConnector.close

connectLegacy()​

connectLegacy(credentials): Promise<void>

Defined in: src/connectors/bigquery.ts:626

Legacy connect method for backward compatibility

Parameters​

credentials​

SourceCredentials

Returns​

Promise<void>

Deprecated​

Use constructor with ConnectorConfig instead

createDebugErrorFactory()​

protected createDebugErrorFactory(debugConfig?): DebugErrorFactory

Defined in: src/connectors/base-connector.ts:843

Helper method for subclasses to create debug-enabled error factory

Parameters​

debugConfig?​

DebugConfig

Returns​

DebugErrorFactory

Inherited from​

BaseConnector.createDebugErrorFactory

escapeIdentifier()​

protected escapeIdentifier(identifier): string

Defined in: src/connectors/base-connector.ts:475

Escape SQL identifiers to prevent injection

Parameters​

identifier​

string

Returns​

string

Inherited from​

BaseConnector.escapeIdentifier

executeParameterizedQuery()​

protected executeParameterizedQuery(sql, parameters?): Promise<QueryResultRow[]>

Defined in: src/connectors/bigquery.ts:205

Execute a parameterized SQL query using BigQuery's named parameters

Parameters​

sql​

string

parameters?​

unknown[] = []

Returns​

Promise<QueryResultRow[]>

Overrides​

BaseConnector.executeParameterizedQuery

executeQuery()​

protected executeQuery(sql): Promise<QueryResultRow[]>

Defined in: src/connectors/bigquery.ts:274

Execute a validated SQL query with security measures

Parameters​

sql​

string

Returns​

Promise<QueryResultRow[]>

Overrides​

BaseConnector.executeQuery

executeWithTimeout()​

protected executeWithTimeout<T>(operation, timeoutMs): Promise<T>

Defined in: src/connectors/base-connector.ts:492

Execute function with timeout protection

Type Parameters​

T​

T

Parameters​

operation​

() => Promise<T>

timeoutMs​

number

Returns​

Promise<T>

Inherited from​

BaseConnector.executeWithTimeout

getDataset()​

getDataset(): string | undefined

Defined in: src/connectors/bigquery.ts:766

Get the currently configured dataset, or undefined if not set.

Returns​

string | undefined

getLastModified()​

getLastModified(table): Promise<Date | null>

Defined in: src/connectors/bigquery.ts:506

Get last modified timestamp for BigQuery tables Uses BigQuery's table metadata when possible

Parameters​

table​

string

Returns​

Promise<Date | null>

Overrides​

BaseConnector.getLastModified

getLocation()​

getLocation(): string

Defined in: src/connectors/bigquery.ts:746

Get current BigQuery location/region

Returns​

string

getMaxTimestamp()​

getMaxTimestamp(table, column): Promise<Date | null>

Defined in: src/connectors/base-connector.ts:606

Get maximum timestamp value from a column

Parameters​

table​

string

column​

string

Returns​

Promise<Date | null>

Inherited from​

BaseConnector.getMaxTimestamp

getMinTimestamp()​

getMinTimestamp(table, column): Promise<Date | null>

Defined in: src/connectors/base-connector.ts:674

Get minimum timestamp value from a column

Parameters​

table​

string

column​

string

Returns​

Promise<Date | null>

Inherited from​

BaseConnector.getMinTimestamp

getProjectId()​

getProjectId(): string

Defined in: src/connectors/bigquery.ts:731

Get BigQuery project ID

Returns​

string

getQueryAnalyzerConfig()​

protected getQueryAnalyzerConfig(): QueryAnalyzerConfig

Defined in: src/connectors/base-connector.ts:799

Get query analyzer configuration

Returns​

QueryAnalyzerConfig

Inherited from​

BaseConnector.getQueryAnalyzerConfig

getRowCount()​

getRowCount(table): Promise<number>

Defined in: src/connectors/base-connector.ts:548

Get row count for a table using parameterized query

Parameters​

table​

string

Returns​

Promise<number>

Inherited from​

BaseConnector.getRowCount

getSchemaCacheStats()​

protected getSchemaCacheStats(): CacheStats

Defined in: src/connectors/base-connector.ts:785

Get schema cache statistics

Returns​

CacheStats

Inherited from​

BaseConnector.getSchemaCacheStats

getTableMetadata()​

getTableMetadata(tableName, timestampColumn?): Promise<{ lastUpdate?: Date; rowCount: number; }>

Defined in: src/connectors/bigquery.ts:693

Legacy get table metadata method for backward compatibility

Parameters​

tableName​

string

timestampColumn?​

string = 'updated_at'

Returns​

Promise<{ lastUpdate?: Date; rowCount: number; }>

Deprecated​

Use getRowCount() and getMaxTimestamp() instead

getTableMetadataFresh()​

protected getTableMetadataFresh(tableName): Promise<TableMetadata | null>

Defined in: src/connectors/base-connector.ts:330

Get fresh table metadata (to be overridden by specific connectors)

Parameters​

tableName​

string

Returns​

Promise<TableMetadata | null>

Inherited from​

BaseConnector.getTableMetadataFresh

getTableSchema()​

getTableSchema(table): Promise<TableSchema>

Defined in: src/connectors/bigquery.ts:446

Get table schema information securely

Parameters​

table​

string

Returns​

Promise<TableSchema>

Overrides​

BaseConnector.getTableSchema

listTables()​

listTables(): Promise<string[]>

Defined in: src/connectors/bigquery.ts:402

List all tables in the project, or in a single dataset when one is set.

When a dataset is configured (via options.dataset or setDataset), the query targets {project}.{dataset}.INFORMATION_SCHEMA.TABLES which only requires dataset-level permissions. Without a dataset the query targets {project}.INFORMATION_SCHEMA.TABLES (project-wide).

Returns​

Promise<string[]>

Overrides​

BaseConnector.listTables

logDebugError()​

protected logDebugError(debugConfig, debugId, operation, context): void

Defined in: src/connectors/base-connector.ts:860

Helper method for subclasses to log debug errors

Parameters​

debugConfig​

DebugConfig | undefined

debugId​

string

operation​

string

context​

Record<string, unknown>

Returns​

void

Inherited from​

BaseConnector.logDebugError

logDebugInfo()​

protected logDebugInfo(debugConfig, debugId, operation, context): void

Defined in: src/connectors/base-connector.ts:851

Helper method for subclasses to log debug information

Parameters​

debugConfig​

DebugConfig | undefined

debugId​

string

operation​

string

context​

Record<string, unknown>

Returns​

void

Inherited from​

BaseConnector.logDebugInfo

logError()​

protected logError(operation, error, context?): void

Defined in: src/connectors/base-connector.ts:774

Helper method for specific connectors to log errors with consistent format

Parameters​

operation​

string

error​

Error

context?​

LogContext

Returns​

void

Inherited from​

BaseConnector.logError

logOperation()​

protected logOperation(operation, context): void

Defined in: src/connectors/base-connector.ts:763

Helper method for specific connectors to log operations with consistent format

Parameters​

operation​

string

context​

LogContext

Returns​

void

Inherited from​

BaseConnector.logOperation

query()​

query<T>(_sql): Promise<T[]>

Defined in: src/connectors/bigquery.ts:722

Legacy query method for backward compatibility

Type Parameters​

T​

T = unknown

Parameters​

_sql​

string

Returns​

Promise<T[]>

Deprecated​

Direct SQL queries are not allowed for security reasons

sanitizeError()​

protected sanitizeError(error): string

Defined in: src/connectors/base-connector.ts:509

Sanitize error messages to prevent information leakage

Parameters​

error​

unknown

Returns​

string

Inherited from​

BaseConnector.sanitizeError

setDataset()​

setDataset(dataset): void

Defined in: src/connectors/bigquery.ts:758

Scope subsequent listTables() calls to a single dataset.

When a dataset is set, listTables() queries {project}.{dataset}.INFORMATION_SCHEMA.TABLES instead of the project-wide INFORMATION_SCHEMA.TABLES. This is required when the service account only has dataset-level permissions.

Parameters​

dataset​

string

Returns​

void

setLocation()​

setLocation(location): void

Defined in: src/connectors/bigquery.ts:738

Set BigQuery location/region

Parameters​

location​

string

Returns​

void

testConnection()​

testConnection(debugConfig?): Promise<boolean>

Defined in: src/connectors/bigquery.ts:281

Test database connection with security validation

Parameters​

debugConfig?​

DebugConfig

Returns​

Promise<boolean>

Overrides​

BaseConnector.testConnection

testConnectionLegacy()​

testConnectionLegacy(): Promise<{ error?: string; success: boolean; tableCount?: number; }>

Defined in: src/connectors/bigquery.ts:662

Legacy test connection method for backward compatibility

Returns​

Promise<{ error?: string; success: boolean; tableCount?: number; }>

Deprecated​

Use testConnection() instead

validateQuery()​

protected validateQuery(sql, tableNames?): Promise<void>

Defined in: src/connectors/base-connector.ts:153

Validate SQL query against security rules with enhanced analysis

Combines traditional pattern matching with advanced query complexity analysis

Parameters​

sql​

string

tableNames?​

string[] = []

Returns​

Promise<void>

Inherited from​

BaseConnector.validateQuery

validateResultSize()​

protected validateResultSize(results): void

Defined in: src/connectors/base-connector.ts:742

Validate that query results don't exceed max rows limit

Parameters​

results​

QueryResultRow[]

Returns​

void

Inherited from​

BaseConnector.validateResultSize