Cube.js Tiva Postgres Driver

Common errors

• Error: The package 'cubejs-tiva-postgres-driver' is not compatible with your current Node.js version. Required: ^14.0.0 || ^16.0.0 || >=17.0.0. Found: v12.x.x

  cause The installed Node.js version does not meet the minimum requirements specified in the package's `engines` field.
  fix Upgrade your Node.js environment to version 14.x, 16.x, or 17.x or newer.

• TypeError: Cannot read properties of undefined (reading 'host') OR Error: Missing required connection option: host

  cause The `driverFactory` function within your `cube.js` configuration is not providing all necessary database connection parameters (e.g., host, port, user, password, database) to the `PostgresDriver` constructor.
  fix Ensure all essential PostgreSQL connection options are passed as properties of an object to the `new PostgresDriver()` call, typically via environment variables (e.g., `process.env.DB_HOST`) or a configuration file.

• SyntaxError: Cannot use import statement outside a module

  cause You are attempting to use ECMAScript Modules (ESM) `import` syntax in a file that is being interpreted as a CommonJS (CJS) module, or in an older Node.js environment that doesn't fully support ESM.
  fix Ensure your Cube.js configuration file (e.g., `cube.js`) is treated as an ESM module by either using a `.mjs` file extension, or by adding `"type": "module"` to your `package.json` file. Alternatively, if feasible, use dynamic `import()` or stick to CJS `require()` if the package provides a CJS entry point.

Warnings

• gotcha This package is a fork of the official Cube.js Postgres driver. It may not receive timely updates, bug fixes, or security patches from the Cube.js core team. Features and API might diverge from the official driver over time.
  Fix: Consider using the official `@cubejs-backend/postgres-driver` for stable and maintained functionality, unless specific modifications in this fork are critical for your project.
• gotcha The package is currently at version `0.0.7`, indicating an early development stage or usage specific to a particular project. It might not be production-ready for general use and could experience frequent API changes without major version bumps.
  Fix: Thoroughly test in your specific environment and review the source code for stability before deploying to production. Be prepared for potential breaking changes in minor versions.
• breaking This driver explicitly requires Node.js versions `^14.0.0 || ^16.0.0 || >=17.0.0`. Attempting to use older Node.js runtimes will result in compatibility errors during installation or runtime.
  Fix: Ensure your Node.js environment is updated to a compatible version (14.x, 16.x, or 17.x and above) to meet the engine requirements specified in `package.json`.

Install

• npm install cubejs-tiva-postgres-driver npm
• yarn add cubejs-tiva-postgres-driver yarn
• pnpm add cubejs-tiva-postgres-driver pnpm

Imports

• PostgresDriver
  wrong:

  const { PostgresDriver } = require('cubejs-tiva-postgres-driver');

  correct:

  import { PostgresDriver } from 'cubejs-tiva-postgres-driver';

  This package is primarily designed for ESM consumption in Node.js 14+ environments. While CJS usage might be possible via bundlers, direct `require()` is not the recommended or typical pattern.
• PostgresDriverOptions
  wrong:

  import { PostgresDriverOptions } from 'cubejs-tiva-postgres-driver';

  correct:

  import type { PostgresDriverOptions } from 'cubejs-tiva-postgres-driver';

  Recommended for type-checking and autocompletion when defining the driver's configuration object within your Cube.js setup. The exact type name might be `DriverConfig` or `PostgresOptions` depending on the fork's specific API.
• * as TivaPostgres
  wrong:

  const TivaPostgres = require('cubejs-tiva-postgres-driver');

  correct:

  import * as TivaPostgres from 'cubejs-tiva-postgres-driver';

  This pattern imports all named exports into a namespace object, allowing access via `TivaPostgres.PostgresDriver` etc. Useful for inspecting available exports or consolidating references.

Quickstart

Demonstrates how to integrate the `cubejs-tiva-postgres-driver` into a basic Cube.js backend configuration using environment variables for database credentials and enabling SSL.

import { CubejsServer } from '@cubejs-backend/server';
import { PostgresDriver } from 'cubejs-tiva-postgres-driver';

const server = new CubejsServer({
  // Replace with your Cube.js configuration, e.g., queryRewrite, externalRefresh
  // For full configuration options, refer to the Cube.js documentation.
  
  driverFactory: (context) => {
    // The context object can be used to pass dynamic information if needed.
    console.log('Initializing Tiva Postgres Driver for Cube.js context:', context);
    return new PostgresDriver({
      host: process.env.DB_HOST ?? 'localhost',
      port: parseInt(process.env.DB_PORT ?? '5432', 10),
      user: process.env.DB_USER ?? 'cube',
      password: process.env.DB_PASSWORD ?? 'password',
      database: process.env.DB_NAME ?? 'cube_db',
      ssl: process.env.DB_SSL === 'true', // Set DB_SSL to 'true' for SSL connection
    });
  },
  // Additional Cube.js options can go here, e.g., `apiSecret`, `schemaPath`
});

server.listen().then(({ app, port }) => {
  console.log(`🚀 Cube.js server is listening on http://localhost:${port}`);
  console.log('Access your Cube.js playground at /cubejs-api');
});