@effectuate/cubejs-mongosql-driver 1.0.0

package/dist/MongoSqlDriver.d.ts

@@ -0,0 +1,238 @@
+/**
+ * MongoSqlDriver — Cube data source driver for MongoDB via MongoSQL.
+ *
+ * See SPEC.md FR-1 (driver protocol), FR-7 (env-var configuration), and
+ * ARCHITECTURE.md §2.1.
+ *
+ * BaseDriver method-list audit (against
+ * `@cubejs-backend/base-driver/dist/src/BaseDriver.d.ts`):
+ *
+ *  Required by DriverInterface (we override these):
+ *   - query(sql, values?, options?)        — REQUIRED, override (delegates + flattens)
+ *   - testConnection()                     — REQUIRED, override (lazy native init)
+ *   - release()                            — override (closes native client)
+ *   - tablesSchema()                       — override (delegate to native)
+ *   - downloadQueryResults(sql, ...)       — override → memory shape; streamImport ignored
+ *                                            (capabilities().streamImport=false; see below)
+ *   - capabilities()                       — override → no export bucket / streaming source
+ *   - nowTimestamp()                       — INHERIT (Date.now())
+ *   - stream(table, values, opts)          — NOT implemented; `streamImport: false`
+ *                                            advertises this. Cube routes the
+ *                                            pre-agg upload path through
+ *                                            `downloadQueryResults` instead.
+ *
+ *  Schema-introspection helpers (BaseDriver default reads information_schema —
+ *  MongoSQL doesn't expose one, so we route every shape through the native
+ *  cached `tablesSchema()` rendering):
+ *   - tablesSchema()                       — override (full snapshot, bulk path)
+ *   - getSchemas()                         — override (DB list from tablesSchema)
+ *   - getTablesForSpecificSchemas(...)     — override (filter tablesSchema by db)
+ *   - getColumnsForSpecificTables(...)     — override (filter tablesSchema by table)
+ *   - capabilities().incrementalSchemaLoading=true — opts Cube into the
+ *                                            granular three-method path; SQL
+ *                                            information_schema queries are
+ *                                            never issued against mongosql.
+ *   - getTablesQuery(schema)               — N/A — runs SQL against information_schema
+ *   - informationSchemaQuery()             — N/A (protected default)
+ *   - tableColumnTypes(table)              — INHERIT (uses query()); only needed for
+ *                                            uploadTableWithIndexes path which we reject
+ *
+ *  Mutation methods (read-only driver — explicit refusal beats silent no-op):
+ *   - createSchemaIfNotExists(schemaName)  — throw
+ *   - dropTable(tableName, options?)       — throw
+ *   - uploadTable(...)                     — throw
+ *   - uploadTableWithIndexes(...)          — throw
+ *   - createTable(...)                     — throw
+ *   - createTableRaw(...)                  — throw
+ *   - loadPreAggregationIntoTable(...)     — INHERIT default (delegates to query())
+ *                                            so partitioned/incremental pre-aggs work
+ *
+ *  Bucket-export (no MongoDB equivalent — SPEC FR-6 says EXPORT_BUCKET unsupported):
+ *   - downloadTable(...)                   — INHERIT (uses query(); fine for memory path)
+ *   - parseBucketUrl / extractFilesFromS3 / extractFilesFromGCS / extractFilesFromAzure
+ *                                          — N/A (only invoked via unload paths we don't expose)
+ *   - readOnly()                           — override → true (signals to Cube/Cube Store)
+ *
+ *  SQL-shape helpers used by Cube but irrelevant to MongoSQL (the dialect class
+ *  handles quoting; the driver does not echo SQL strings):
+ *   - quoteIdentifier(id)                  — INHERIT (default uses '"', dialect class
+ *                                            in MongoSqlQuery overrides to backticks)
+ *   - param(i)                             — INHERIT
+ *   - wrapQueryWithLimit({query, limit})   — INHERIT (mutates the object in place)
+ *
+ *  Static:
+ *   - dialectClass()                       — override → MongoSqlQuery
+ */
+import { BaseDriver } from '@cubejs-backend/base-driver';
+import type { DownloadQueryResultsOptions, DownloadQueryResultsResult, DownloadTableData, DriverCapabilities, ExternalCreateTableOptions, IndexesSQL, QueryColumnsResult, QueryOptions, QuerySchemasResult, QueryTablesResult, TableColumn, TableStructure } from '@cubejs-backend/base-driver';
+import { type TablesSchema } from './native.js';
+import { MongoSqlQuery } from './MongoSqlQuery.js';
+import type { MongoSqlConfig } from './types.js';
+/**
+ * Cube driver class. Cube instantiates this when CUBEJS_DB_TYPE=mongosql.
+ *
+ * Construction is cheap and pure: env vars are read and validated, but no
+ * native client is created. The native client is created lazily on the first
+ * `testConnection()` / `query()` / `tablesSchema()` call so that throwing in
+ * the constructor reports config errors crisply (Cube wraps construction
+ * exceptions less helpfully than runtime ones).
+ *
+ * **Configuration env vars (see `./config.ts` and README "Configuration"):**
+ *
+ *   Cube-standard (`CUBEJS_DB_*`):
+ *     - `CUBEJS_DB_URL` / `CUBEJS_DB_URI` — full MongoDB connection string
+ *     - `CUBEJS_DB_HOST` / `_PORT` / `_USER` / `_PASS` / `_NAME` — composed URI parts
+ *     - `CUBEJS_DB_NAME` — database (also required separately by the driver)
+ *     - `CUBEJS_DB_SSL` — `tls=true|false`
+ *     - `CUBEJS_DB_MAX_POOL` / `_MIN_POOL` — `maxPoolSize` / `minPoolSize`
+ *     - `CUBEJS_DB_QUERY_TIMEOUT` — per-query `maxTimeMS` (duration string or ms)
+ *     - `CUBEJS_DB_IDLE_TIMEOUT` — `maxIdleTimeMS` (duration string or ms)
+ *
+ *   MongoDB-specific (`CUBEJS_MONGOSQL_*`):
+ *     - `_SCHEMA_SOURCE` — `collection` (default), `file`, or `atlas-sql`
+ *     - `_SCHEMA_FILE` — path (required if `_SCHEMA_SOURCE=file`)
+ *     - `_SCHEMA_REFRESH_SEC` — background refresh cadence in seconds
+ *     - `_SCHEMA_FAIL_OPEN` — `true` to soft-fail initial schema load
+ *     - `_QUERY_TIMEOUT_MS` — (legacy) bare-ms timeout; overridden by
+ *       `CUBEJS_DB_QUERY_TIMEOUT` when both set
+ *     - `_MAX_ROWS` — row cap per query
+ *     - `_APP_NAME` — `appName` (shows up in `serverStatus().connections`)
+ *     - `_MAX_CONNECTING` — `maxConnecting`
+ *     - `_WAIT_QUEUE_TIMEOUT_MS` — `waitQueueTimeoutMS`
+ *     - `_CONNECT_TIMEOUT_MS` — `connectTimeoutMS`
+ *     - `_SOCKET_TIMEOUT_MS` — `socketTimeoutMS`
+ *     - `_SERVER_SELECTION_TIMEOUT_MS` — `serverSelectionTimeoutMS`
+ *     - `_HEARTBEAT_FREQUENCY_MS` — `heartbeatFrequencyMS`
+ *     - `_RETRY_WRITES` / `_RETRY_READS` — `retryWrites` / `retryReads`
+ *     - `_COMPRESSORS` — `compressors`
+ *
+ *   User-set URI params (those already encoded in `CUBEJS_DB_URL/URI`) ALWAYS
+ *   win — we only append env-driven params for keys the URI doesn't already
+ *   specify.
+ */
+export declare class MongoSqlDriver extends BaseDriver {
+    private readonly resolvedConfig;
+    private client;
+    constructor(config?: Partial<MongoSqlConfig>);
+    /** Test hook: surface the config the driver resolved from constructor + env. */
+    _config(): Readonly<MongoSqlConfig>;
+    testConnection(): Promise<void>;
+    query<R = unknown>(sql: string, values?: unknown[], options?: QueryOptions): Promise<R[]>;
+    tablesSchema(): Promise<TablesSchema>;
+    /**
+     * Cube's incremental-schema-loading entry point #1.
+     *
+     * Returns the list of schemas (databases) we expose. BaseDriver's
+     * default issues `SELECT table_schema ... FROM information_schema.tables`,
+     * which MongoSQL has no equivalent for. We re-render from the cached
+     * `tablesSchema()` snapshot — which the native side already keeps
+     * fresh via the background refresh task (SPEC FR-3 / ARCHITECTURE §3.2).
+     * Each call into `client.tablesSchema()` returns a fresh clone of the
+     * cached snapshot, so the cost is O(N) in catalog column count — for
+     * the typical few-thousand-cell catalog this is sub-millisecond on the
+     * hot path (no native I/O, no `__sql_schemas` round-trip).
+     *
+     * Driver only ever exposes the database configured at construction
+     * (FR-7 — `CUBEJS_DB_NAME`), so the returned list has at most one
+     * entry. An empty list is possible if no schemas have been loaded
+     * yet (e.g. `testConnection()` was never called or the schema source
+     * is empty); Cube handles that case the same way it would for the
+     * SQL path's empty resultset.
+     */
+    getSchemas(): Promise<QuerySchemasResult[]>;
+    /**
+     * Cube's incremental-schema-loading entry point #2.
+     *
+     * For each requested schema, returns its table list from the cached
+     * `tablesSchema()`. Schemas the snapshot doesn't know about are
+     * silently dropped — mirrors the SQL path's "WHERE schema IN (...)"
+     * which would naturally exclude unknown names. Passing an empty
+     * `schemas` array returns an empty result with no native I/O cost
+     * beyond a single cache read.
+     */
+    getTablesForSpecificSchemas(schemas: QuerySchemasResult[]): Promise<QueryTablesResult[]>;
+    /**
+     * Cube's incremental-schema-loading entry point #3.
+     *
+     * For each requested `(schema_name, table_name)`, returns one row
+     * per column with `column_name` and `data_type`. `data_type` is the
+     * Cube generic-type string emitted by the native side (`string`,
+     * `int`, `bigint`, `decimal`, `boolean`, `timestamp`, `text`) — the
+     * same values that surface in `tablesSchema()`. Unknown tables are
+     * silently dropped, same contract as `getTablesForSpecificSchemas`.
+     *
+     * `attributes` is forwarded verbatim from the column descriptor IF
+     * a future native version supplies one — but the Rust `do_tables_schema`
+     * (crates/native/src/client.rs:314) always emits `attributes: []` today,
+     * so in production this is effectively always an empty array. We do
+     * not emit `primaryKey` automatically — MongoDB's implicit `_id` IS a
+     * primary key, but tagging it without explicit schema annotation would
+     * surface as a foreign-key target in Cube's relationship inference and
+     * break heuristic joins. The TS-side forwarding path exists for a
+     * future Rust change where `__sql_schemas` documents' attribute fields
+     * are propagated; callers that need the tag today still must encode
+     * it explicitly in their __sql_schemas document AND in a Rust patch
+     * that surfaces it through `ColumnSchema::attributes`.
+     *
+     * `foreign_keys` is not derivable from MongoDB schema documents — the
+     * field is omitted (Cube's `QueryColumnsResult` declares it as
+     * optional via the spread of `TableColumnQueryResult`).
+     */
+    getColumnsForSpecificTables(tables: QueryTablesResult[]): Promise<QueryColumnsResult[]>;
+    release(): Promise<void>;
+    downloadQueryResults(sql: string, values?: unknown[], options?: DownloadQueryResultsOptions): Promise<DownloadQueryResultsResult>;
+    capabilities(): DriverCapabilities;
+    readOnly(): boolean;
+    createSchemaIfNotExists(_schemaName: string): Promise<void>;
+    dropTable(_tableName: string, _options?: QueryOptions): Promise<unknown>;
+    uploadTable(_table: string, _columns: TableStructure, _tableData: DownloadTableData): Promise<void>;
+    uploadTableWithIndexes(_table: string, _columns: TableStructure, _tableData: DownloadTableData, _indexesSql: IndexesSQL, _uniqueKeyColumns: string[] | null, _queryTracingObj: unknown, _externalOptions: ExternalCreateTableOptions): Promise<void>;
+    createTable(_quotedTableName: string, _columns: TableColumn[]): Promise<void>;
+    createTableRaw(_query: string): Promise<void>;
+    static dialectClass(): typeof MongoSqlQuery;
+    private ensureClient;
+}
+/**
+ * Make every row's key set identical by null-filling missing keys.
+ *
+ * **Mutates `rows` in place** — callers must not retain references to
+ * the pre-normalize array if they need the original sparse shape. The
+ * returned reference is the same array.
+ *
+ * **Why this exists.** Mongosql's `$project` stage that references a
+ * nested-path expression (e.g. `agent.displayName` on a docs collection)
+ * OMITS the field entirely when the source path is missing on the
+ * underlying document — it does not emit `null`. This bites downstream
+ * consumers whenever the row at index 0 happens to be sparser than later
+ * rows; `ORDER BY <nested-field> ASC` is the most common way this
+ * surfaces, but any query whose row 0 lacks a key that later rows have
+ * triggers the same.
+ *
+ * Downstream consumers (notably Cube's native `getFinalQueryResult`
+ * transform in `@cubejs-backend/native`) compile their row→member
+ * extraction plan from the keys present in **row 0**. A sparse row 0
+ * causes Cube to drop the column from every row in the response — even
+ * rows that DO have the value. Reproduced empirically against the
+ * `configs` collection (`SELECT id, agent_display_name FROM configs ...
+ * ORDER BY agent_display_name ASC LIMIT 500` → 500 rows, all missing
+ * `configs.agent_display_name`, even though 497/500 source docs have it).
+ *
+ * **Fix shape.** Take the union of keys across all rows and null-fill
+ * each row so every row has every key. We can't simply look at `row[0]`
+ * because that's the symptom. Iteration is O(rows × cols). At the
+ * `MAX_ROWS=100000` pre-agg cap with a ~20-column projection this is
+ * roughly 2M property-existence checks and stays under 100ms in practice.
+ *
+ * `downloadQueryResults` uses the authoritative type list instead of
+ * a key union (the union would miss columns absent from every row); that
+ * variant is implemented inline at the call site, not via this helper.
+ */
+declare function normalizeRowShape<R>(rows: Array<Record<string, unknown>>): R[];
+/**
+ * Test-only export. Lets `tests/unit/driver.test.ts` exercise the
+ * key-union null-fill in isolation without spinning up the driver.
+ * Not part of the public API.
+ */
+export declare const _normalizeRowShapeForTests: typeof normalizeRowShape;
+export {};
+//# sourceMappingURL=MongoSqlDriver.d.ts.map

package/dist/MongoSqlDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MongoSqlDriver.d.ts","sourceRoot":"","sources":["../src/MongoSqlDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACf,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAmC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAA+B,MAAM,YAAY,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD,OAAO,CAAC,MAAM,CAA6B;gBAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAK5C,gFAAgF;IACzE,OAAO,IAAI,QAAQ,CAAC,cAAc,CAAC;IAMpB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IA+BzF,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;IAK3D;;;;;;;;;;;;;;;;;;;OAmBG;IACmB,UAAU,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAKjE;;;;;;;;;OASG;IACmB,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAc9G;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACmB,2BAA2B,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAoBvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,0BAA0B,CAAC;IA6EtB,YAAY,IAAI,kBAAkB;IAsBlC,QAAQ,IAAI,OAAO;IAMb,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxE,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,iBAAiB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAIM,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,iBAAiB,EAC7B,WAAW,EAAE,UAAU,EACvB,iBAAiB,EAAE,MAAM,EAAE,GAAG,IAAI,EAClC,gBAAgB,EAAE,OAAO,EACzB,gBAAgB,EAAE,0BAA0B,GAC3C,OAAO,CAAC,IAAI,CAAC;IAIM,WAAW,CAAC,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;WAMrD,YAAY,IAAI,OAAO,aAAa;IAMlD,OAAO,CAAC,YAAY;CAMrB;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,iBAAS,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,CAgBvE;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0BAAoB,CAAC"}