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::Client 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::Client 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::Client 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.

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::Client if the server rejects CREATE TABLE IF NOT EXISTS.

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::Client 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::Client 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::Client 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::Client 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.