CUBRID System Catalog — Section Overview

CUBRID System Catalog — Section Overview

What this section covers

A relational engine has to describe itself to itself, through SQL. The user (and the engine) ask two flavours of self-description question:

• Static — schema. What classes exist? What columns? What indexes? Who owns each one? What privileges? These are answered by system catalog classes — _db_class, _db_attribute, _db_index, _db_auth, … — real heap tables that hold one row per schema object, plus a layer of system views (db_class, db_attribute, …) that re-shape the same data for SQL clients. The rows are written by DDL and read by every plan compile.
• Dynamic — runtime state. Which threads are blocked? How full is the page buffer? Where is the log tail? What locks are held? These are answered by SHOW commands — SHOW THREADS, SHOW PAGE BUFFER STATUS, SHOW LOG HEADER — relations whose rows do not exist on disk, but are synthesised on demand from server memory whenever a query touches them.

This section bundles the two together because they form one coherent surface: every question a user (or the engine itself) can ask about “what is happening inside this database” is answered by some row in some table-shaped thing, and the executor reaches both kinds of thing through identical scan operators. The static surface and the dynamic surface are the same idea — self-description through SQL — applied at two different time horizons.

flowchart TB
    subgraph staticcat["Static surface — SQL-visible system classes"]
        DEF["system_catalog_definition<br/>(per-class meta-schema:<br/>attributes, constraints,<br/>grants, row_init)"]
        INST["catcls_install<br/>(3-pass bootstrap at createdb)"]
        SYSCL["_db_class, _db_attribute,<br/>_db_index, _db_auth, ...<br/>+ db_class, db_attribute,<br/>... 22 system views"]
        DEF --> INST --> SYSCL
    end
    subgraph dynamiccat["Dynamic surface — synthesised at query time"]
        REWRITE["SHOW name<br/>=> SELECT * FROM<br/>(PT_SHOWSTMT)"]
        SCAN["S_SHOWSTMT_SCAN<br/>(virtual scan operator)"]
        SYNTH["per-SHOWSTMT_TYPE<br/>start / next / end<br/>(reads thread state,<br/>page buffer counters,<br/>log header, locks, ...)"]
        REWRITE --> SCAN --> SYNTH
    end
    EXEC["Executor scan_next_scan loop<br/>(uniform: heap, B+Tree, list,<br/>JSON-table, SHOW, all leaves)"]
    SYSCL --> EXEC
    SYNTH --> EXEC

This section is not about the on-disk catalog format that backs the system classes — OR_CLASSREP, CTID, the dedicated catalog heap — that is cubrid-catalog-manager.md under DDL & Schema. Catalog-manager is the storage the system classes ride on; this section is the facade the SQL surface sees. The boundary between the two is that _db_class is a real CUBRID class with attributes and constraints (this section’s territory), while the bytes of its rows on disk are encoded as OR_CLASSREP records in the dedicated catalog heap (DDL & Schema territory).

The two halves

Static surface — cubrid-system-catalog-classes.md. How CUBRID defines and bootstraps the SQL-visible system class family — _db_class, _db_attribute, _db_index, _db_auth, … — through a data-driven framework. Each class is encoded as a cubschema::system_catalog_definition value (attributes + constraints + grants + optional row initializer); a single system_catalog_builder consumes the value to issue db_create_class -> smt_add_attribute -> sm_update_class -> constraint/grant — the same DDL primitives a user CREATE TABLE takes. System views (db_class, db_attribute, …) carry their query spec as a SQL string literal compiled into the binary, installed via db_add_query_spec in a second pass. The whole install runs once at createdb against the root-class anchor and goes dormant after that.

Dynamic surface — cubrid-show-commands.md. How CUBRID exposes server-internal runtime state — volume headers, log headers, heap and B+Tree capacity, critical sections, threads, page buffer, transaction tables, timezones — as queryable virtual tables. The pipeline is uniform: the parser rewrites SHOW <name> into SELECT * FROM (PT_SHOWSTMT); the optimiser emits an access spec with TARGET_SHOWSTMT; the executor opens an S_SHOWSTMT_SCAN; per-SHOWSTMT_TYPE start/next/end function pointers in show_scan.c synthesise tuples on demand by reading critical-section state, thread-pool state, log-header fields, page-buffer counters. The trick that makes the rest of SQL work — predicates, projections, sorts, joins on SHOW outputs — is that the leaf is uniform with every other scan operator, so the executor never learns that “threads” is not a real table.

Reading order

The two halves are independent in code (the static surface never calls into SHOW; SHOW reads runtime memory, never the static catalog tables). Pick by what you are working on:

1. If you are reading DDL / schema / query optimisation, start with cubrid-system-catalog-classes.md. The 24 system classes and 22 system views are referenced in almost every other doc in the repository — DDL execution, the optimiser, authentication, partition, trigger, the PL family. Knowing what _db_class, _db_attribute, _db_auth look like as SQL tables is foundational.
2. If you are debugging a live system, start with cubrid-show-commands.md. SHOW is the diagnostic surface you reach for at runtime. Once you know how the static catalog works (the analogous idea applied to schema), the SHOW pipeline becomes “the same self-description trick, but for transient state”.

If you are reading the implementation of the system classes (how does _db_class actually get its rows on disk?), that is cubrid-catalog-manager.md in DDL & Schema — read it after the static-surface doc, because the catalog-manager doc assumes you already know what _db_class is.

Cross-cutting concerns

• Both surface through the executor’s scan registry. cubrid-system-catalog-classes builds real classes whose rows live in the catalog heap, so reads run through the standard S_HEAP_SCAN. cubrid-show-commands adds S_SHOWSTMT_SCAN to the same SCAN_TYPE registry that lists heap, list, B+Tree, set, method, and JSON-table scans. From the executor’s point of view both are “ordinary leaves” — predicates, projections, sorts, joins, and aggregates work uniformly. See cubrid-scan-manager.md and cubrid-query-executor.md.
• Static catalog is written once at createdb; user DDL writes its content thereafter. The 24-class meta-schema is installed by catcls_install exactly once, against the root-class anchor that createdb seeds. After that, every user CREATE TABLE adds rows to _db_class / _db_attribute / _db_index; every ALTER updates them; DROP deletes them. The DDL pipeline (read cubrid-ddl-execution.md) and the in-memory schema graph (cubrid-class-object.md) are the consumers and writers; this section’s static-surface doc is the definition of the tables they read and write.
• SHOW commands expose every other subsystem’s internal state. SHOW THREADS reads the worker pool (cubrid-thread-worker-pool.md, cubrid-thread-manager-ng.md). SHOW LOG HEADER reads the log manager (cubrid-log-manager.md). SHOW PAGE BUFFER STATUS reads the page-buffer manager (cubrid-page-buffer-manager.md). SHOW LOCKS reads the lock manager (cubrid-lock-manager.md). SHOW TRAN TABLES reads the transaction subsystem (cubrid-transaction.md). SHOW TIMEZONES reads the loaded timezone library (cubrid-timezone.md). For a cross-section reader, SHOW is effectively a discovery surface for the rest of the engine.
• The static catalog and SHOW share the same _db_collation / _db_charset data. The i18n primitives surface twice — through _db_charset / _db_collation rows installed at createdb (this section, static surface) and through SHOW LOCALES / SHOW COLLATION synthesised at query time (this section, dynamic surface). The two readings agree because both ultimately consult the same libcubrid_collations.so blob loaded at server boot. See cubrid-charset-collation.md.
• The on-disk catalog backs both halves. _db_class rows live in the dedicated catalog heap described in cubrid-catalog-manager.md. SHOW does not write storage but reads internal state of subsystems that do live in storage (page buffer, log manager). The boundary is intentional — this section is the SQL-visible facade; storage is cubrid-catalog-manager (DDL & Schema) and the per-subsystem detail docs.

Detail-doc summaries

Doc	Surface	One-line summary
cubrid-system-catalog-classes.md	static	Data-driven framework that defines and bootstraps _db_class, _db_attribute, _db_index, …, 24 classes + 22 views, each encoded as a system_catalog_definition value and installed by a single system_catalog_builder at createdb; system views carry a SQL string-literal query spec compiled into the binary.
cubrid-show-commands.md	dynamic	SHOW <name> rewritten to SELECT * FROM (PT_SHOWSTMT); S_SHOWSTMT_SCAN virtual scan; per-SHOWSTMT_TYPE start/next/end function pointers in show_scan.c synthesise tuples from server-internal state (threads, latches, page buffer, log header, transaction tables, timezones) on demand.

Adjacent sections

• DDL & Schema. The on-disk catalog format that backs the system classes — OR_CLASSREP, CLS_INFO, CTID, the dedicated catalog heap, statistics — lives in cubrid-catalog-manager.md. The DDL pipeline that writes user-class rows into _db_class is cubrid-ddl-execution.md. The in-memory SM_CLASS graph that consumes _db_class rows on every plan compile is cubrid-class-object.md. For the full schema-change story read those alongside this section’s static-surface doc — DDL writes the rows, catalog-manager stores them, this section defines the tables they live in.
• Query Processing. Every compiled query reads the static catalog (to resolve _db_class rows into SM_CLASS graphs and to consult statistics for cardinality estimates) and may read the dynamic catalog (when the user issues SHOW or queries virtual tables). The scan-manager dispatch table that hosts S_HEAP_SCAN for catalog-class reads and S_SHOWSTMT_SCAN for SHOW is described in cubrid-scan-manager.md and cubrid-query-executor.md.
• Server Architecture. boot_sr invokes catcls_init + catcls_install once at createdb to install the static surface — see cubrid-boot.md. SHOW commands directly expose almost every other server-architecture subsystem (see the cross-cutting list above). The locator’s MOP table that paginates catalog reads is cubrid-locator.md.
• Storage Engine. Catalog and system-class rows are heap rows; SHOW reads internal state of cubrid-page-buffer-manager.md, cubrid-log-manager.md, cubrid-lock-manager.md directly, bypassing the SQL surfaces those subsystems normally hide behind.
• Internationalisation. Both i18n primitives surface through this section — statically via _db_charset / _db_collation rows, dynamically via SHOW LOCALES / SHOW COLLATION / SHOW TIMEZONES / SHOW FULL TIMEZONES. See cubrid-overview-i18n-specialty.md.