CockroachDB is a distributed SQL database that implements PostgreSQL's wire protocol. For a database client, this compatibility is valuable: it lets you reuse a large part of the Postgres infrastructure, from type parsing to the connection pool. But wire-compatible doesn't mean identical. The system catalog differs, some maintenance operations have no equivalent, and several of Postgres's physical concepts make no sense in a distributed engine.
QoreDB's CockroachDB driver starts from this observation. It is deliberately thin: it relies on a shared pg_compat module and only overrides the methods whose behavior genuinely diverges.
A shared foundation with the PostgreSQL driver
In QoreDB, every driver implements the DataEngine trait. CockroachDB and PostgreSQL both use sqlx with the PgPool pool, the same connection-string construction logic, the same session mechanism and the same transaction handling. Rather than duplicating this code, the project exposes utility functions in pg_compat.rs: test_connection, connect, execute_in_namespace, execute_stream_in_namespace, insert_row, update_row, delete_row, routine and trigger handling, and foreign-key peeking.
The CockroachDB driver consumes these functions and only adds code for the areas where the engine behaves differently. This avoids drift between two closely related drivers and guarantees that any bug fix in the shared logic immediately benefits both engines.
Filtering out CockroachDB-specific namespaces
PostgreSQL exposes system schemas such as information_schema, pg_catalog and pg_toast. CockroachDB adds two that have no strict equivalent on the Postgres side: crdb_internal groups together the engine's own metadata, and pg_extension contains virtual extensions. Showing them in the sidebar would be noisy and misleading, since the user cannot write to them in the usual way.
The driver's list_namespaces method therefore reads pg_catalog.pg_namespace, explicitly excluding these two schemas. This filtering isn't a side effect: it's the direct translation of a modeling choice, namely to expose only what the user can manipulate.
No materialized views in the collection list
On Postgres, list_collections distinguishes three types: Table, View and materialized view. CockroachDB supports regular views but not materialized views in the Postgres sense. The driver's query is therefore limited to information_schema.tables and maps only two types. The code doesn't try to emulate anything: if the engine doesn't distinguish a third category, the driver doesn't fabricate one.
Maintenance: why only ANALYZE is exposed
CockroachDB's storage engine has little in common with Postgres's. It has no physical tables in the traditional MVCC sense, no TOAST files, no B-tree indexes to rebuild manually. The VACUUM, REINDEX and CLUSTER operations have no direct equivalent on the CRDB side, because the engine handles these aspects internally through its garbage collector and its range distributor.
Describing a table without relying on pg_stat_user_tables
The shared describe_table_core helper takes a flag indicating whether the pg_stat_user_tables view is available. Postgres uses it to get a quick estimate of the row count via n_live_tup. CockroachDB doesn't expose this view in the same way, so the driver passes false for this parameter.
The practical consequence is simple: a table's details panel shows the columns, constraints, indexes and foreign keys, but the cardinality estimate is left to an explicit COUNT query when the user asks for it. A missing number is better than a wrong one coming from a view that doesn't share the same semantics as on Postgres.
Connection string and default database
Building the connection string uses the build_pg_connection_string helper, with one particularity: if the user doesn't specify a database, the driver uses defaultdb, the database CockroachDB ships with at installation. The default port is 26257, and the password is URL-encoded to handle special characters. The module's tests cover this last point: a password containing at signs, slashes or symbols is correctly escaped before transmission.
What this choice means in real-world use
In practice, a QoreDB user connecting to a CockroachDB instance gets the same experience as on Postgres for everything that matters day to day: SQL editor with autocompletion, result streaming, inline editing, explicit transactions, listing of routines and triggers, schema-based navigation. This consistency comes from the fact that these functions are literally the same Rust code.
The differences show up where they genuinely exist: no VACUUM option in the maintenance menu, no internal schemas visible in the sidebar, no cardinality estimate in the table's detail view. These differences are owned and documented in the code itself, not hidden behind an emulation layer that would end up lying about the engine.
Honest compatibility rather than illusory
Wire compatibility between CockroachDB and PostgreSQL is a gift for a database client, provided you use it without naivety. Reusing the pool, the parsing and the execution logic is legitimate because these layers are identical. Reusing maintenance or statistics views would be less so, because they touch the storage engine. By cleanly separating the shared foundation from the divergences, QoreDB's CockroachDB driver respects what the engine actually exposes, and stays predictable for the user.
Stay updated on new releases
Subscribe to get product releases, new drivers notifications, and technical tutorials.