{"id":10702,"library":"cubejs-server","title":"Cube.js Server","description":"Cube.js Server (`@cubejs-backend/server`) is the core Node.js component of the Cube.js analytics platform, an open-source semantic layer for building analytical applications. It functions as a backend microservice that manages connections to various data sources (SQL databases, data warehouses), handles query queuing, caching, and pre-aggregations, and exposes a GraphQL/REST API for frontend applications. The current stable version, as per recent npm releases, is around 1.6.x, while the user provided 0.33.8 which is an older minor version. Cube.js releases new versions frequently, sometimes introducing breaking changes even in minor updates within a major series (e.g., 0.x.x versions). Its key differentiators include a SQL-based data schema for defining measures and dimensions, advanced pre-aggregation for performance, robust caching, enterprise-grade security (JWT tokens, row-level security), and visualization-agnostic API support, allowing integration with any frontend framework or BI tool.","status":"active","version":"0.33.8","language":"javascript","source_language":"en","source_url":"https://github.com/zhjuncai/cube.js","tags":["javascript","typescript"],"install":[{"cmd":"npm install cubejs-server","lang":"bash","label":"npm"},{"cmd":"yarn add cubejs-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add cubejs-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for processing Cube.js data schema files.","package":"@cubejs-backend/schema-compiler","optional":false},{"reason":"Core component for query execution, caching, and scheduling.","package":"@cubejs-backend/query-orchestrator","optional":false},{"reason":"PostgreSQL database driver. Install the appropriate driver for your data source (e.g., `mysql2`, `mongodb`, `clickhouse`).","package":"pg","optional":true},{"reason":"Used internally for handling API routes and middleware. Often a direct or transitive dependency.","package":"express","optional":false},{"reason":"Used by Express for parsing request bodies.","package":"body-parser","optional":false},{"reason":"Express middleware for enabling Cross-Origin Resource Sharing.","package":"cors","optional":false}],"imports":[{"note":"The primary class for instantiating the Cube.js backend. Note the correct package name `@cubejs-backend/server`.","wrong":"const CubejsServer = require('cubejs-server');","symbol":"CubejsServer","correct":"import { CubejsServer } from '@cubejs-backend/server';"},{"note":"TypeScript interface for configuring the Cube.js server instance.","symbol":"CubejsServerOptions","correct":"import { CubejsServerOptions } from '@cubejs-backend/server';"},{"note":"Used for generating Cube.js schema files dynamically or programmatically. Often used in setup scripts.","wrong":"import { CubejsServer } from '@cubejs-backend/server'; const { generate } = new CubejsServer();","symbol":"generate","correct":"import { generate } from '@cubejs-backend/server';"}],"quickstart":{"code":"import express from 'express';\nimport { CubejsServer } from '@cubejs-backend/server';\nimport dotenv from 'dotenv';\nimport path from 'path';\n\ndotenv.config({ path: path.resolve(process.cwd(), '.env') });\n\nasync function main() {\n  const server = new CubejsServer({\n    // Required for security and API token generation\n    // Use process.env.CUBEJS_API_SECRET ?? '' for production\n    apiSecret: process.env.CUBEJS_API_SECRET ?? 'YOUR_API_SECRET',\n    \n    // Configure your database connection\n    dbType: process.env.CUBEJS_DB_TYPE ?? 'postgres',\n    dbHost: process.env.CUBEJS_DB_HOST ?? 'localhost',\n    dbName: process.env.CUBEJS_DB_NAME ?? 'cubejs_data',\n    dbUser: process.env.CUBEJS_DB_USER ?? 'cubejs_user',\n    dbPass: process.env.CUBEJS_DB_PASS ?? 'cubejs_password',\n    \n    // Path to your Cube.js schema files (e.g., .js, .yml)\n    // Defaults to 'schema' folder in the root\n    // schemaPath: path.resolve(process.cwd(), 'schema'),\n\n    // Port for the Cube.js API\n    port: parseInt(process.env.PORT ?? '4000', 10),\n\n    // Enable developer playground in development mode\n    devPlayground: process.env.NODE_ENV === 'development',\n\n    // Additional server configuration options\n    // full stack traces for development debugging\n    extendContext: (req) => ({\n      traceId: req.headers['x-request-id'] || 'no-trace',\n    }),\n  });\n\n  const app = express();\n  // Integrate Cube.js with your Express app\n  await server.initApp(app);\n\n  app.listen(server.options.port, () => {\n    console.log(`🚀 Cube.js server is running on http://localhost:${server.options.port}`);\n    if (server.options.devPlayground) {\n      console.log(`▶️ Cube.js Playground available at http://localhost:${server.options.port}`);\n    }\n  });\n}\n\nmain().catch((e) => {\n  console.error('Failed to start Cube.js server:', e);\n  process.exit(1);\n});\n","lang":"typescript","description":"This quickstart demonstrates how to set up and launch a basic Cube.js API server using Express. It shows essential configuration for database connection, API secret, port, and enabling the developer playground."},"warnings":[{"fix":"Update `package.json` to use `@cubejs-backend/server` and modify all import statements to `from '@cubejs-backend/server'`.","message":"The package name for the Cube.js server was changed from `cubejs-server` (deprecated) to `@cubejs-backend/server`. Using the old package name will result in an outdated, unmaintained version and potential compatibility issues. Ensure all dependencies and imports reflect `@cubejs-backend/server`.","severity":"breaking","affected_versions":"<=0.32.0 (for old package name), >=0.33.0 (for new package name)"},{"fix":"Run `npm install <your-db-driver-package>` (e.g., `npm install pg`) or `yarn add <your-db-driver-package>`.","message":"Database drivers (e.g., `pg`, `mysql2`, `mongodb`, `clickhouse`) are peer dependencies of Cube.js. You must explicitly install the correct driver package for your specific database(s) alongside `@cubejs-backend/server`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the official Cube.js changelog for your specific version range and adapt your code and configuration files (`.env`, `schema/`, `cube.config.js`) accordingly.","message":"Cube.js `0.x.x` versions, while actively developed, may introduce breaking changes in minor releases. Always consult the release notes and changelog before upgrading, especially regarding schema definitions, configuration formats (e.g., from `cube.js` to `cube.config.js` or `.env` for database credentials), and API scopes.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Upgrade your Node.js environment to a supported LTS version (e.g., Node.js 16, 18, or 20, as recommended by Cube.js documentation). Update your `engines` field in `package.json`.","message":"Node.js version support has evolved. Node.js v12 and v15 support was dropped with v0.32.0, and v14 was deprecated shortly after. Newer versions prioritize Node.js v16 and above. Using unsupported Node.js versions can lead to unexpected errors or stability issues.","severity":"breaking","affected_versions":">=0.32.0"},{"fix":"Consider deploying Cube.js as a standalone service (e.g., via Docker) and connecting to it from your main application via its API. Explore Cube Cloud for managed deployments.","message":"Embedding Cube.js directly into existing Express applications using `initApp(app)` has been deprecated in favor of deploying Cube.js as a separate microservice. While still functional, this pattern is less performant and reliable for production deployments, especially as Cube.js evolves towards Rust-based components.","severity":"deprecated","affected_versions":">=0.24.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the necessary database driver: `npm install pg` (for PostgreSQL) or `yarn add pg`.","cause":"The required database driver for PostgreSQL is not installed. This applies to any database type (e.g., `mysql2` for MySQL).","error":"Error: Cannot find module 'pg'"},{"fix":"Ensure that your `.env` file exists and contains all necessary `CUBEJS_DB_*` variables for your database, and that `dotenv.config()` is called correctly at the start of your application. Verify database credentials and host accessibility.","cause":"Cube.js cannot connect to the database because environment variables (like `CUBEJS_DB_TYPE`, `CUBEJS_DB_HOST`, `CUBEJS_DB_NAME`, etc.) are either missing or incorrect, or the `.env` file is not loaded.","error":"Error: Data source is not configured. Please check your CUBEJS_DB_* environment variables."},{"fix":"Set `CUBEJS_API_SECRET` in your `.env` file (e.g., `CUBEJS_API_SECRET=YOUR_SECURE_SECRET`) or pass it directly in the `CubejsServer` constructor options. Ensure it's a strong, unique secret for production.","cause":"The `CUBEJS_API_SECRET` environment variable or the `apiSecret` option in `CubejsServer` constructor is not provided. This secret is crucial for securing your Cube.js API.","error":"Error: 'CUBEJS_API_SECRET' is not set. It is required to secure your API. Please set it via environment variable or in Cube.js options."},{"fix":"Try deleting the `.cubestore` directory in your project root to clear the corrupted metastore. Note that this will clear your cache and pre-aggregations, which will be rebuilt on restart.","cause":"This low-level error often indicates a corrupted Cube Store metastore, especially when using Cube Store as the caching/queue engine, typically due to improper shutdown.","error":"thread 'main' panicked at 'called `Option::unwrap()` on a `None` value'"}],"ecosystem":"npm"}