¶ (c) Technocore - All Rights Reserved.
NOTICE: All information contained herein is, and remains
the property of TechnoCore.
The intellectual and technical concepts contained
herein are proprietary to TechnoCore and dissemination of this information or reproduction of this material
is strictly forbidden unless prior written permission is obtained
from TechnoCore.
¶ ObjDataDDL
The ObjDataDDL class is a core component of the Axion framework responsible for handling Data Definition Language (DDL) operations. It provides a high-level abstraction for interacting with the database schema, allowing for the creation, modification, and deletion of database objects like tables and columns.
¶ Class Overview
ObjDataDDL inherits from Objects.Object and ObjDataSql.ObjDataSql, combining base object functionalities and SQL execution capabilities. Its primary purpose is to manage the database schema in a portable and database-agnostic way (where possible).
Key functionalities include:
- Checking for the existence of tables and columns
- Adding, renaming, and deleting columns
- Retrieving schema information such as primary keys and column types
- Getting package and collation information from the configuration
- Multi-database support (MySQL/MariaDB, MSSQL, SQLite, MongoDB)
¶ Global Caching
The module uses global module-level variables for efficient caching of frequently accessed configuration values:
BUFFER_PACKAGE: Caches the current package nameBUFFER_ARCHETYPE: Caches the archetype nameBUFFER_COLLATION: Caches the database collation settingADD_COL_BUFFER: Tracks columns that have been added during the session
These buffers prevent repeated configuration lookups and database queries for the same information.
¶ Methods
¶ get_collation() -> str
Retrieves the default database collation from the system's configuration (config.yaml). The result is cached in BUFFER_COLLATION to improve performance on subsequent calls.
Returns: Collation string (e.g., utf8mb4_unicode_ci)
¶ get_package() -> str
Retrieves the current package name from the configuration or environment variable AXION_PACKAGE. This is crucial for package-specific operations. The result is cached in BUFFER_PACKAGE.
Returns: Package name in uppercase
¶ get_package_and_archetype() -> tuple[str, str]
Retrieves both the current package and its archetype from the def_package table. An archetype can be considered a "parent" or "template" package. Falls back to configuration if database query fails. The results are cached in BUFFER_PACKAGE and BUFFER_ARCHETYPE.
Returns: Tuple of (package_name, archetype_name)
¶ has_table(table: str, remote: DatabaseConnection = 0) -> bool
Checks if a table exists in the database. Supports MySQL/MariaDB, MSSQL, SQLite, and MongoDB.
table: The name of the table to check (can include schema prefix likedatabase.table)remote: Optional remote database connection. Defaults to primary connection
Returns: True if the table exists, False otherwise
Database-specific behavior:
- MySQL/MariaDB: Queries
information_schema.tables - MSSQL: Queries
INFORMATION_SCHEMA.TABLES - SQLite: Queries
sqlite_master - MongoDB: Uses
list_collection_names()
¶ rename_column(table, from_field, to_field, field_type)
Renames a column in a specified table.
table(str): The name of the table.from_field(str): The current name of the column.to_field(str): The new name for the column.field_type(str): The data type of the column, used if the column needs to be created.
¶ get_columns(table_reference)
Retrieves a list of all column names for a given table.
table_reference(str): The name of the table.
¶ has_column(table: str, column_name: str, db: DatabaseConnection | str = "") -> bool
Checks if a specific column exists within a given table. Uses ADD_COL_BUFFER to track columns added during the session to avoid redundant checks.
table: The name of the table (can include schema prefix)column_name: The name of the column to checkdb: Optional database connection or empty string for default
Returns: True if the column exists, False otherwise
Security note: Returns True if the table or column name contains single quotes to prevent SQL injection attempts.
¶ get_column_type(table_base, column_name)
Retrieves the data type and maximum length of a specific column.
table_base(str): The name of the table.column_name(str): The name of the column.
Returns a tuple (data_type, length).
¶ add_column(table_name: str, column_name: str, column_type: str) -> int
Adds a new column to a specified table if it does not already exist. Automatically handles collation for MySQL databases and normalizes special column types.
table_name: The name of the tablecolumn_name: The name of the new columncolumn_type: The SQL data type for the new column (e.g.,TEXT,VARCHAR(255))
Returns: 1 on success, 0 on failure
Type normalization:
label,choose_one,signature,question,image,score,lookup,repeat,counter,grid,location→textdate_time→datetime
Features:
- Checks table existence before attempting to add column
- Skips if column already exists
- Updates
ADD_COL_BUFFERto track added columns - Handles schema-prefixed table names (e.g.,
database.table)
¶ add_columns(table: str, columns_to_add: list[tuple]) -> None
Adds multiple columns to a table from a list of tuples. Iterates through the list and calls add_column() for each tuple.
table: The name of the tablecolumns_to_add: A list of(column_name, column_type)tuples
¶ delete_column(table_name: str, column_name: str) -> None
Deletes a column from a table if it exists. Also removes the column from ADD_COL_BUFFER if present.
table_name: The name of the tablecolumn_name: The name of the column to delete
Behavior: Skips deletion if column doesn't exist (logs debug message)
¶ Optimizations
Recent optimizations applied to improve code quality and maintainability:
- Fixed duplicate call bug: Removed duplicate
add_column()call inadd_columns()method - Fixed typo: Corrected method name from
sql_get_vales()tosql_get_values() - Simplified boolean returns: Replaced verbose if/else blocks with direct boolean expressions (
return col_check > 0) - Improved exception handling: Changed bare
except BaseExceptionto specificexcept Exceptionwith proper logging - Fixed type hints: Updated
dbparameter type fromDatabaseConnection = 0toDatabaseConnection | str = "" - Removed unused import: Cleaned up unused
Decoratorsimport after caching strategy decision
¶ Implementation Notes
Caching Strategy: The module uses global module-level variables (BUFFER_*) for caching instead of decorator-based caching. This approach provides:
- Simpler control over cache invalidation
- Explicit visibility of cached values
- Better performance for frequently accessed configuration values
- Consistency across all instances of the class
SQL Injection Protection: The has_column() method includes basic SQL injection prevention by returning True if single quotes are detected in table or column names.
Multi-database Support: Methods automatically detect the database type using is_my_sql(), is_ms_sql(), and is_mongo() helper methods to generate appropriate queries for each database system.
Updated: 2025-12-12