Struct TableDefinition 

pub struct TableDefinition {
    pub name: String,
    pub schema: Option<String>,
    pub database: Option<String>,
    pub columns: Vec<ColumnDefinition>,
    /* private fields */
}

A table definition.

This struct defines the schema of a table including its name, optional schema and database names, and column definitions.

Example

Using the fluent builder pattern:

use hyperdb_api::{TableDefinition, Result};
use hyperdb_api_core::types::{SqlType, Nullability};

let table = TableDefinition::new("users")
    .add_required_column("id", SqlType::int())
    .add_nullable_column("name", SqlType::text());

let sql = table.to_create_sql(true)?;
assert!(sql.contains("CREATE TABLE"));

Fields

name: String

Table name.

schema: Option<String>

Schema name.

database: Option<String>

Database name.

columns: Vec<ColumnDefinition>

Column definitions.

Implementations

impl TableDefinition

pub fn new(name: impl Into<String>) -> Self

Creates a new table definition.

pub fn from_table_name<T>(table_name: T) -> Result<Self>

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

Creates a table definition from a validated TableName.

This constructor uses a pre-validated TableName, ensuring all name components have already passed validation (non-empty, within length limits).

Example

use hyperdb_api::{TableDefinition, TableName};
use hyperdb_api_core::types::{SqlType, Nullability};

// First create a validated TableName
let table_name = TableName::try_new("users")?
    .with_schema("public")?
    .with_database("mydb")?;

// Then create TableDefinition from it
let table = TableDefinition::from_table_name(table_name)?
    .add_required_column("id", SqlType::int());

assert_eq!(table.name, "users");
assert_eq!(table.schema, Some("public".to_string()));
assert_eq!(table.database, Some("mydb".to_string()));

// Direct conversion from string also works
let table2 = TableDefinition::from_table_name("public.users")?;
assert_eq!(table2.schema, Some("public".to_string()));

Errors

Returns the conversion error (typically Error::InvalidName) if table_name cannot be parsed into a TableName.

pub fn with_schema(self, schema: impl Into<String>) -> Self

Sets the schema name (fluent builder pattern).

Example

use hyperdb_api::TableDefinition;
use hyperdb_api_core::types::{SqlType, Nullability};

let table = TableDefinition::new("Extract")
    .with_schema("Extract")
    .add_required_column("id", SqlType::int());

pub fn with_database(self, database: impl Into<String>) -> Self

Sets the database name (fluent builder pattern).

pub fn with_persistence(self, persistence: Persistence) -> Self

Sets the persistence (fluent builder pattern).

Example

use hyperdb_api::{TableDefinition, Persistence};
use hyperdb_api_core::types::SqlType;

let temp_table = TableDefinition::new("temp_data")
    .with_persistence(Persistence::Temporary)
    .add_required_column("id", SqlType::int());
assert_eq!(temp_table.get_persistence(), Persistence::Temporary);

pub fn get_persistence(&self) -> Persistence

Returns the persistence setting.

pub fn set_persistence(&mut self, persistence: Persistence)

Sets the persistence.

pub fn add_nullable_column( self, name: impl Into<String>, sql_type: SqlType, ) -> Self

Adds a nullable column using SqlType (fluent builder pattern).

Example

use hyperdb_api::TableDefinition;
use hyperdb_api_core::types::SqlType;

let table = TableDefinition::new("products")
    .add_nullable_column("name", SqlType::text())
    .add_nullable_column("price", SqlType::numeric(18, 2));

pub fn add_required_column( self, name: impl Into<String>, sql_type: SqlType, ) -> Self

Adds a required (non-nullable) column using SqlType (fluent builder pattern).

Example

use hyperdb_api::TableDefinition;
use hyperdb_api_core::types::SqlType;

let table = TableDefinition::new("products")
    .add_required_column("id", SqlType::int())
    .add_required_column("name", SqlType::text());

pub fn add_nullable_column_with_collation( self, name: impl Into<String>, sql_type: SqlType, collation: impl Into<String>, ) -> Self

Adds a nullable column with a collation (fluent builder pattern).

Example

use hyperdb_api::TableDefinition;
use hyperdb_api_core::types::SqlType;

let table = TableDefinition::new("products")
    .add_nullable_column_with_collation("name", SqlType::text(), "en_US");

pub fn add_required_column_with_collation( self, name: impl Into<String>, sql_type: SqlType, collation: impl Into<String>, ) -> Self

Adds a required (non-nullable) column with a collation (fluent builder pattern).

Example

use hyperdb_api::TableDefinition;
use hyperdb_api_core::types::SqlType;

let table = TableDefinition::new("products")
    .add_required_column_with_collation("name", SqlType::text(), "en_US");

pub fn add_column_def(self, column: ColumnDefinition) -> Self

Adds a ColumnDefinition directly (fluent builder pattern).

pub fn column_count(&self) -> usize

Returns the number of columns.

pub fn columns(&self) -> &[ColumnDefinition]

Returns the column definitions.

pub fn column(&self, index: usize) -> &ColumnDefinition

Returns the column at the given position.

Panics

Panics if the index is out of bounds.

pub fn column_by_name(&self, name: &str) -> Option<&ColumnDefinition>

Returns the column with the given name, if it exists.

pub fn column_position_by_name(&self, name: &str) -> Option<usize>

Returns the position of the column with the given name.

pub fn table_name(&self) -> String

Returns the table name (unqualified, escaped).

This returns just the table name portion, properly escaped for use in SQL.

Example

use hyperdb_api::TableDefinition;

let table = TableDefinition::new("Extract").with_schema("Extract");
// "Extract" is quoted because it contains uppercase letters (to preserve case)
assert_eq!(table.table_name(), "\"Extract\"");

pub fn schema_name(&self) -> Option<String>

Returns the schema name (escaped), if set.

pub fn database_name(&self) -> Option<String>

Returns the database name (escaped), if set.

pub fn qualified_name(&self) -> String

Returns the qualified table name (escaped).

Format: database.schema.table (if all parts are set, unquoted if valid identifiers)

pub fn set_table_name(&mut self, name: impl Into<String>)

Sets the table name.

pub fn to_table_name(&self) -> Result<TableName>

Converts this TableDefinition to a validated TableName.

This method validates all name components (table, schema, database) and returns a type-safe TableName. Use this when you need to ensure the names are valid.

Errors

Returns an error if any name component is empty or exceeds the PostgreSQL identifier limit.

Example

use hyperdb_api::TableDefinition;

let table = TableDefinition::new("users")
    .with_schema("public")
    .with_database("mydb");

// Validate all names
let table_name = table.to_table_name()?;
assert_eq!(table_name.to_string(), "\"mydb\".\"public\".\"users\"");

pub fn to_create_sql(&self, fail_if_exists: bool) -> Result<String>

Generates CREATE TABLE SQL.

Arguments

• fail_if_exists - If true, the statement will fail if the table exists. If false, uses CREATE TABLE IF NOT EXISTS.

Example

use hyperdb_api::{TableDefinition, Result};
use hyperdb_api_core::types::{SqlType, Nullability};

let table = TableDefinition::new("users")
    .add_required_column("id", SqlType::int());

let sql = table.to_create_sql(true)?;
assert_eq!(sql, r#"CREATE TABLE users (id INTEGER NOT NULL)"#);

Errors

Returns Error::Other with message "Table must have at least one column" if this definition has no columns.

pub fn to_drop_sql(&self, fail_if_not_exists: bool) -> String

Generates DROP TABLE SQL.

Arguments

• fail_if_not_exists - If true, the statement will fail if the table doesn’t exist. If false, uses DROP TABLE IF EXISTS.

Trait Implementations

impl Clone for TableDefinition

fn clone(&self) -> TableDefinition

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TableDefinition

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

Formats the value using the given formatter.

impl Default for TableDefinition

fn default() -> Self

Returns the “default value” for a type.

impl From<&str> for TableDefinition

fn from(name: &str) -> Self

Converts to this type from the input type.

impl From<String> for TableDefinition

fn from(name: String) -> Self

Converts to this type from the input type.