cube-js/cube · error · PostgresError

PostgreSQL can not work with table names longer than 63 symb

Error message

PostgreSQL can not work with table names longer than 63 symbols. Consider using the 'sqlAlias' attribute in your cube definition for ${quotedTableName}.

What it means

PostgreSQL identifiers (table names) are limited to 63 bytes by NAMEDATALEN. Cube's PostgresDriver checks the quoted table name length in createTable before issuing DDL and throws this error when a pre-aggregation table name would exceed that limit, since PostgreSQL would silently truncate it and break lookups. The error suggests using the 'sqlAlias' attribute in the cube definition to shorten generated names.

Source

Thrown at packages/cubejs-postgres-driver/src/PostgresDriver.ts:446

    PostgresDriver.checkValuesLimit(values);

    return this.withConnection(async (conn) => {
      await this.prepareConnection(conn);

      const res = await conn.query({
        text: query,
        values: values || [],
        types: {
          getTypeParser: this.getTypeParser,
        },
      });
      return res;
    });
  }

  public async createTable(quotedTableName: string, columns: TableColumn[]): Promise<void> {
    if (quotedTableName.length > 63) {
      throw new PostgresError('PostgreSQL can not work with table names longer than 63 symbols. ' +
        `Consider using the 'sqlAlias' attribute in your cube definition for ${quotedTableName}.`);
    }
    return super.createTable(quotedTableName, columns);
  }

  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  public async query<R = unknown>(query: string, values: unknown[], options?: QueryOptions): Promise<R[]> {
    const result = await this.queryResponse(query, values);
    return result.rows;
  }

  public async downloadQueryResults(query: string, values: unknown[], options: DownloadQueryResultsOptions): Promise<DownloadQueryResultsResult> {
    if (options.streamImport) {
      return this.stream(query, values, options);
    }

    const res = await this.queryResponse(query, values);
    return {

View on GitHub (pinned to 7d981676b3)

Solutions

  1. Add a short 'sqlAlias' attribute to the cube definition so generated pre-aggregation table names fit within 63 characters
  2. Shorten the cube name or pre-aggregation name that produces the long table name
  3. Reduce the schema name length so schema + table fits in 63 symbols

Example fix

// before
cube('very_long_cube_name_that_generates_huge_preaggregation_table_identifiers', { ... });
// after
cube('very_long_cube_name_that_generates_huge_preaggregation_table_identifiers', {
  sqlAlias: 'plg_sales', // short alias keeps table names under 63 chars
  ...
});
Defensive patterns

Strategy: validation

Validate before calling

function assertTableFitsPgLimit(quotedTableName) {
  if (quotedTableName.length > 63) {
    throw new Error(`Table name exceeds PostgreSQL 63-char limit: ${quotedTableName.length} chars`);
  }
}
assertTableFitsPgLimit('"my_schema"."my_long_preaggregation_table_name"');

Type guard

const isPgSafeIdentifier = (name) => typeof name === 'string' && name.length <= 63;

Try / catch

try {
  await driver.createTable(quotedTableName, columns);
} catch (e) {
  if (String(e.message).includes('longer than 63 symbols')) {
    console.error('Add sqlAlias to the cube definition to shorten table names');
  }
  throw e;
}

Prevention

When it happens

Trigger: uploadTableWithIndexes calls createTable with a quotedTableName longer than 63 characters — typically a long auto-generated pre-aggregation table name derived from a cube/alias with a very long name or deeply nested members.

Common situations: Cubes with long names or many long member names producing long pre-aggregation table identifiers; schemas whose names add to the quoted length; projects migrated to PostgreSQL without considering the 63-byte identifier limit.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/ce9a5e06427ffb08. Report an issue: GitHub.