Struct Catalog 

pub struct Catalog<'conn> { /* private fields */ }

Provides catalog operations for database metadata.

Example

use hyperdb_api::{Connection, Catalog, CreateMode, Result};

fn main() -> Result<()> {
    let conn = Connection::connect("localhost:7483", "example.hyper", CreateMode::CreateIfNotExists)?;
    let catalog = Catalog::new(&conn);

    // Check if a schema exists
    if !catalog.has_schema("my_schema")? {
        catalog.create_schema("my_schema")?;
    }

    // List tables
    let tables = catalog.get_table_names("my_schema")?;
    for table in tables {
        println!("Table: {}", table);
    }
    Ok(())
}

Implementations

impl<'conn> Catalog<'conn>

pub fn new(connection: &'conn Connection) -> Self

Creates a new Catalog for the given connection.

pub fn create_database(&self, path: &str) -> Result<()>

Creates a new database file (delegates to Connection).

Errors

Forwards the error from Connection::create_database.

pub fn drop_database(&self, path: &str) -> Result<()>

Drops (deletes) a database file (delegates to Connection).

Errors

Forwards the error from Connection::drop_database.

pub fn attach_database(&self, path: &str, alias: Option<&str>) -> Result<()>

Attaches a database file to the connection.

Once attached, the database can be queried and modified. The database is identified by its alias (or by its path if no alias is provided).

Arguments

• path - The path to the database file to attach.
• alias - Optional alias for the database. If None, the database is attached without an explicit alias (typically using its filename).

Errors

Returns an error if the database file doesn’t exist or if attachment fails.

pub fn detach_database(&self, alias: &str) -> Result<()>

Detaches a database from the connection.

After detaching, the database file is released and can be accessed externally (e.g., copied, moved, etc.). All pending updates are written to disk before detaching.

Arguments

• alias - The alias of the database to detach.

Errors

Returns an error if the database is not attached or if detachment fails.

pub fn detach_all_databases(&self) -> Result<()>

Detaches all databases from the connection.

This is useful for cleanup before closing a connection or when you need to release all database files.

Errors

Returns an error if the databases could not be detached.

pub fn create_schema<T>(&self, schema_name: T) -> Result<()>

where T: TryInto<SchemaName>, Error: From<T::Error>,

Creates a schema.

Errors

• Returns an error if schema_name cannot be converted to a SchemaName.
• Returns Error::Server if the server rejects CREATE SCHEMA IF NOT EXISTS.

pub fn get_schema_names<T>(&self, database: Option<T>) -> Result<Vec<String>>

where T: TryInto<DatabaseName>, Error: From<T::Error>,

Returns a list of schema names in the database.

Arguments

• database - The database name, or None to use the first database in the search path.

Returns

A vector of schema names.

Errors

Returns an error if the query fails.

pub fn get_table_names<T>(&self, schema: T) -> Result<Vec<String>>

where T: TryInto<SchemaName>, Error: From<T::Error>,

Returns a list of table names in the given schema.

Arguments

• schema - The schema name (can include database qualifier).

Returns

A vector of table names.

Errors

Returns an error if the query fails.

pub fn has_schema<T>(&self, schema: T) -> Result<bool>

where T: TryInto<SchemaName>, Error: From<T::Error>,

Checks whether a schema exists.

Arguments

• schema - The schema name (can include database qualifier).

Returns

true if the schema exists, false otherwise.

Errors

• Returns an error if schema cannot be converted to a SchemaName.
• Returns Error::Server if the pg_catalog.pg_namespace lookup query fails.

pub fn has_table<T>(&self, table_name: T) -> Result<bool>

where T: TryInto<TableName>, Error: From<T::Error>,

Checks whether a table exists.

Arguments

• table_name - The table name (can include database and schema qualifiers).

Returns

true if the table exists, false otherwise.

Errors

• Returns an error if table_name cannot be converted to a TableName.
• Returns Error::Server if the pg_catalog.pg_tables lookup query fails.

pub fn get_table_definition<T>(&self, table_name: T) -> Result<TableDefinition>

where T: TryInto<TableName>, Error: From<T::Error>,

Retrieves the table definition for an existing table.

The returned definition carries the full schema Hyper is able to record: column names and types, NOT NULL, DEFAULT expressions, and the assumed key constraints (TableConstraint). Real PRIMARY KEY, UNIQUE, FOREIGN KEY, and CHECK constraints are rejected by the engine at CREATE TABLE, so a Hyper table never carries one.

Arguments

• table_name - The table name (can include database and schema qualifiers).

Returns

A TableDefinition representing the table’s schema.

Errors

Returns an error if the table does not exist or if retrieval fails.

Example

use hyperdb_api::{Connection, Catalog, Result};

fn main() -> Result<()> {
    let conn = Connection::without_database("localhost:7483")?;
    let catalog = Catalog::new(&conn);

    let table_def = catalog.get_table_definition("public.products")?;
    println!("Columns: {}", table_def.column_count());
    for col in table_def.columns() {
        println!("  - {}: {}", col.name, col.type_name());
    }
    Ok(())
}

pub fn create_table(&self, table_def: &TableDefinition) -> Result<()>

Creates a table from a definition.

Arguments

• table_def - The table definition describing the table to create.

Errors

Returns an error if the table already exists or if creation fails.

pub fn create_table_if_not_exists( &self, table_def: &TableDefinition, ) -> Result<()>

Creates a table from a definition if it doesn’t exist.

Unlike create_table, this method does not fail if the table already exists.

Errors

• Returns Error::InvalidTableDefinition if table_def cannot be rendered as valid SQL (zero columns, bad identifiers).
• Returns Error::Server if the server rejects CREATE TABLE IF NOT EXISTS.

pub fn copy_table<S, D>( &self, source: S, destination: D, ) -> Result<CopyTableReport>

where S: TryInto<TableName>, Error: From<S::Error> + From<D::Error>, D: TryInto<TableName>,

Copies a table, reproducing its schema instead of inferring it.

CREATE TABLE … AS SELECT derives the destination schema from the query’s result columns, which carry types but no constraints, so every column of a CTAS copy comes out nullable with no defaults and no keys. This method reflects the source schema out of pg_catalog, issues an explicit CREATE TABLE, and only then moves the rows with INSERT … SELECT.

Source and destination may live in different databases; qualify the names and both sides are addressed directly. Note that once a second database is attached to the session, Hyper can no longer resolve unqualified DDL (create statement could not resolve the schema), so cross-database callers should qualify both names fully.

Fidelity

NOT NULL, DEFAULT, COLLATE, ASSUMED PRIMARY KEY, and ASSUMED UNIQUE are carried across. Enforced PRIMARY KEY, UNIQUE, FOREIGN KEY, and CHECK cannot be: Hyper rejects all four at CREATE TABLE, so no table this engine wrote has one to begin with. Should one turn up anyway — in a .hyper written by an engine with index support — it is reported as unpreserved rather than downgraded to its ASSUMED form, which would swap an enforced constraint for an unenforced one and call it preserved.

Defaults are the one class that can be partly lost. Hyper stores non-literal defaults database-qualified — NOW() reads back as "mydb"."pg_catalog"."now"() — and copying that text verbatim into another database would leave the copy depending on "mydb" being attached. Such defaults are dropped and listed in CopyTableReport::unpreserved rather than reproduced unsoundly. A successful return does not imply full fidelity — check CopyTableReport::is_fully_preserved.

Arguments

• source - The table to copy from (may include database/schema qualifiers).
• destination - The table to create (may include database/schema qualifiers).

Errors

• Error::NotFound if source does not exist.
• Error::Server if the destination already exists.

Example

use hyperdb_api::{Catalog, Connection, Result};

fn main() -> Result<()> {
    let conn = Connection::without_database("localhost:7483")?;
    let catalog = Catalog::new(&conn);

    let report = catalog.copy_table("public.orders", "backup.public.orders")?;
    println!("copied {} rows", report.rows_copied);
    for item in &report.unpreserved {
        eprintln!("not preserved - {item}");
    }
    Ok(())
}

pub fn drop_table<T>(&self, table_name: T) -> Result<()>

where T: TryInto<TableName>, Error: From<T::Error>,

Drops a table.

Arguments

• table_name - The table name (can include database and schema qualifiers).

Errors

Returns an error if the table doesn’t exist or if deletion fails.

pub fn drop_table_if_exists<T>(&self, table_name: T) -> Result<()>

where T: TryInto<TableName>, Error: From<T::Error>,

Drops a table if it exists.

Unlike drop_table, this method does not fail if the table doesn’t exist.

Errors

• Returns an error if table_name cannot be converted to a TableName.
• Returns Error::Server if the server rejects DROP TABLE IF EXISTS.

pub fn drop_schema<T>(&self, schema_name: T, cascade: bool) -> Result<()>

where T: TryInto<SchemaName>, Error: From<T::Error>,

Drops a schema.

Arguments

• schema_name - The schema name (can include database qualifier).
• cascade - If true, drop all objects in the schema.

Errors

Returns an error if the schema doesn’t exist or if deletion fails.

pub fn drop_schema_if_exists<T>( &self, schema_name: T, cascade: bool, ) -> Result<()>

where T: TryInto<SchemaName>, Error: From<T::Error>,

Drops a schema if it exists.

Errors

• Returns an error if schema_name cannot be converted to a SchemaName.
• Returns Error::Server if the server rejects DROP SCHEMA IF EXISTS — typically because cascade was false and the schema is not empty.

pub fn get_row_count<T>(&self, table_name: T) -> Result<i64>

where T: TryInto<TableName>, Error: From<T::Error>,

Returns the approximate row count for a table.

This executes SELECT COUNT(*) FROM table_name.

Example

let catalog = Catalog::new(&conn);
let count = catalog.get_row_count("public.users")?;
println!("Users: {}", count);

Errors

• Returns an error if table_name cannot be converted to a TableName.
• Returns Error::Server if the SELECT COUNT(*) query fails (e.g. table does not exist).

pub fn get_column_names<T>(&self, table_name: T) -> Result<Vec<String>>

where T: TryInto<TableName>, Error: From<T::Error>,

Returns the column names for a table.

Example

let catalog = Catalog::new(&conn);
let columns = catalog.get_column_names("public.users")?;
for col in &columns {
    println!("Column: {}", col);
}

Errors

Forwards the error from get_table_definition — invalid table_name, missing table, or a failed catalog query.

pub fn get_database_names(&self) -> Result<Vec<String>>

Returns a list of attached database names.

Example

let catalog = Catalog::new(&conn);
let databases = catalog.get_database_names()?;
for db in &databases {
    println!("Database: {}", db);
}

Errors

Returns Error::Server if the SELECT datname FROM pg_catalog.pg_database query fails or a streaming error occurs while draining the result.

Trait Implementations

impl<'conn> Debug for Catalog<'conn>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.