Schema Introspection

Author: kakserpom

README.md

@@ -85,6 +85,7 @@ $posts = $driver->queryAll('SELECT * FROM posts WHERE author_id = ?', [12345]);
 - Optional persistent connections (with connection pooling)
 - **Automatic retry** with exponential backoff for transient failures
 - Custom `SqlxException` class with error codes for precise error handling
+- **Schema introspection** via `describeTable()` for table column metadata
 
 ---
 
@@ -726,6 +727,30 @@ $driver = Sqlx\DriverFactory::make([
   for
   debugging.
 
+#### Schema Introspection
+
+- `describeTable(string $table, ?string $schema = null): array` – returns column metadata for the specified table.
+
+```php
+$columns = $driver->describeTable('users');
+// Returns:
+// [
+//   ['name' => 'id', 'type' => 'integer', 'nullable' => false, 'default' => null, 'ordinal' => 1],
+//   ['name' => 'email', 'type' => 'varchar(255)', 'nullable' => false, 'default' => null, 'ordinal' => 2],
+//   ['name' => 'created_at', 'type' => 'timestamp', 'nullable' => true, 'default' => 'now()', 'ordinal' => 3],
+// ]
+
+// With explicit schema
+$columns = $driver->describeTable('users', 'public');
+```
+
+Each column entry contains:
+- `name` – Column name (string)
+- `type` – Database-specific type (string), e.g., `varchar(255)`, `integer`, `timestamp`
+- `nullable` – Whether `NULL` is allowed (bool)
+- `default` – Default value expression (string|null)
+- `ordinal` – 1-based column position (int)
+
 ---
 
 ### Sqlx\PreparedQuery

src/dbms/mssql/inner.rs

@@ -1,6 +1,20 @@
 #![allow(clippy::needless_pass_by_value)]
 use crate::php_sqlx_impl_driver_inner;
 
+/// SQL query to describe table columns using `information_schema`.
+pub const DESCRIBE_TABLE_QUERY: &str = r"
+SELECT
+    column_name AS name,
+    data_type + COALESCE('(' + CAST(character_maximum_length AS VARCHAR) + ')', '') AS type,
+    CASE WHEN is_nullable = 'YES' THEN 1 ELSE 0 END AS nullable,
+    column_default AS [default],
+    ordinal_position AS ordinal
+FROM information_schema.columns
+WHERE table_name = $table
+  AND table_schema = COALESCE($schema, SCHEMA_NAME())
+ORDER BY ordinal_position
+";
+
 pub const SETTINGS: Settings = Settings {
     collapsible_in_enabled: true,
     escaping_double_single_quotes: true,

src/dbms/mysql/inner.rs

@@ -2,6 +2,20 @@
 
 use crate::php_sqlx_impl_driver_inner;
 
+/// SQL query to describe table columns using `information_schema`.
+pub const DESCRIBE_TABLE_QUERY: &str = r"
+SELECT
+    column_name AS name,
+    column_type AS type,
+    is_nullable = 'YES' AS nullable,
+    column_default AS `default`,
+    ordinal_position AS ordinal
+FROM information_schema.columns
+WHERE table_name = $table
+  AND table_schema = COALESCE($schema, DATABASE())
+ORDER BY ordinal_position
+";
+
 pub const SETTINGS: Settings = Settings {
     collapsible_in_enabled: true,
     escaping_double_single_quotes: true,

src/dbms/postgres/inner.rs

@@ -1,5 +1,20 @@
 #![allow(clippy::needless_pass_by_value)]
 use crate::php_sqlx_impl_driver_inner;
+
+/// SQL query to describe table columns using `information_schema`.
+pub const DESCRIBE_TABLE_QUERY: &str = r"
+SELECT
+    column_name AS name,
+    data_type || COALESCE('(' || character_maximum_length::text || ')', '') AS type,
+    is_nullable = 'YES' AS nullable,
+    column_default AS default,
+    ordinal_position AS ordinal
+FROM information_schema.columns
+WHERE table_name = $table
+  AND table_schema = COALESCE($schema, current_schema())
+ORDER BY ordinal_position
+";
+
 pub const SETTINGS: Settings = Settings {
     collapsible_in_enabled: true,
     escaping_double_single_quotes: true,

src/driver.rs

@@ -921,6 +921,48 @@ macro_rules! php_sqlx_impl_driver {
                     .query_grouped_column_dictionary(query, parameters, None)
             }
 
+            /// Describes table columns with their types and metadata.
+            ///
+            /// Returns information about each column in the specified table, including
+            /// name, type, nullability, default value, and ordinal position.
+            ///
+            /// # Parameters
+            /// - `table`: Name of the table to describe.
+            /// - `schema`: Optional schema name. If `None`, uses the database default schema.
+            ///
+            /// # Returns
+            /// An array of associative arrays, each containing:
+            /// - `name`: Column name (string)
+            /// - `type`: Database-specific column type (string, e.g., "varchar(255)", "int")
+            /// - `nullable`: Whether the column allows NULL values (bool)
+            /// - `default`: Default value for the column (string|null)
+            /// - `ordinal`: Column position, 1-based (int)
+            ///
+            /// # Example
+            /// ```php
+            /// $columns = $driver->describeTable('users');
+            /// // [
+            /// //   ['name' => 'id', 'type' => 'integer', 'nullable' => false, 'default' => null, 'ordinal' => 1],
+            /// //   ['name' => 'email', 'type' => 'varchar(255)', 'nullable' => false, 'default' => null, 'ordinal' => 2],
+            /// // ]
+            ///
+            /// // With schema
+            /// $columns = $driver->describeTable('users', 'public');
+            /// ```
+            ///
+            /// # Exceptions
+            /// Throws an exception if:
+            /// - the table or schema name is invalid (contains invalid characters);
+            /// - the query fails to execute;
+            /// - the table does not exist.
+            pub fn describe_table(
+                &self,
+                table: &str,
+                schema: Option<&str>,
+            ) -> $crate::error::Result<Vec<Zval>> {
+                self.driver_inner.describe_table(table, schema)
+            }
+
             /// Executes an INSERT/UPDATE/DELETE query and returns affected row count.
             ///
             /// # Arguments

src/inner_driver.rs

@@ -904,6 +904,57 @@ macro_rules! php_sqlx_impl_driver_inner {
                     })
             }
 
+            /// Describes table columns with their types and metadata.
+            ///
+            /// Returns information about each column in the specified table, including
+            /// name, type, nullability, default value, and ordinal position.
+            ///
+            /// # Parameters
+            /// - `table_name`: Name of the table to describe.
+            /// - `schema`: Optional schema name. If `None`, uses the database default schema.
+            ///
+            /// # Returns
+            /// An array of associative arrays, each containing:
+            /// - `name`: Column name
+            /// - `type`: Database-specific column type (e.g., "varchar(255)", "int")
+            /// - `nullable`: Whether the column allows NULL values
+            /// - `default`: Default value for the column, or NULL if none
+            /// - `ordinal`: Column position (1-based)
+            ///
+            /// # Errors
+            /// Returns an error if:
+            /// - the table or schema name is invalid (contains invalid characters);
+            /// - the query fails to execute;
+            /// - the table does not exist.
+            pub fn describe_table(
+                &self,
+                table_name: &str,
+                schema: Option<&str>,
+            ) -> $crate::error::Result<Vec<Zval>> {
+                // Validate identifiers to prevent SQL injection
+                if !is_valid_ident(table_name) {
+                    return Err(SqlxError::InvalidIdentifier {
+                        value: table_name.to_string(),
+                    });
+                }
+                if let Some(s) = schema {
+                    if !is_valid_ident(s) {
+                        return Err(SqlxError::InvalidIdentifier {
+                            value: s.to_string(),
+                        });
+                    }
+                }
+
+                let mut params = BTreeMap::new();
+                params.insert("table".to_string(), ParameterValue::String(table_name.to_string()));
+                params.insert(
+                    "schema".to_string(),
+                    schema.map_or(ParameterValue::Null, |s| ParameterValue::String(s.to_string())),
+                );
+
+                self.query_all(DESCRIBE_TABLE_QUERY, Some(params), Some(true))
+            }
+
             /// Begins a new SQL transaction and places it into the transaction stack.
             ///
             /// This method must be called before executing transactional operations