Schema Inspect

Common errors

• ModuleNotFoundError: No module named 'schemainspect'

  cause The `schemainspect` library is not installed in the current Python environment.
  fix Install the library using pip: `pip install schemainspect`

• sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgresql

  cause While `schemainspect` depends on SQLAlchemy, it does not directly install database drivers (like `psycopg2` for PostgreSQL, `mysqlclient` for MySQL, etc.) which are required by SQLAlchemy to connect to your specific database.
  fix Install the appropriate database driver for your database. For PostgreSQL, run: `pip install psycopg2-binary`. For MySQL, use `pip install mysqlclient`.

• KeyError: 'your_table_name' when accessing schema.tables['your_table_name']

  cause The specified table name either does not exist in the inspected schema, or there's a case sensitivity mismatch. Database object names are often case-sensitive or automatically lowercased/uppercased depending on the database and DDL.
  fix Verify the exact table name and its casing by iterating through `schema.tables.keys()` to see all available table names. For example: `print(schema.tables.keys())`.

Warnings

• gotcha The library uses timestamp-based versioning (e.g., 3.1.1663587362) instead of semantic versioning. This means minor updates could potentially introduce behavioral changes without a major version increment, making it harder to track breaking changes.
  Fix: Always test `schemainspect` thoroughly after updating, especially if relying on specific schema inspection behaviors.
• gotcha While the project aims to support 'possibly others,' its strong dependency on `pgspecial` and the project's focus imply a primary and most robust support for PostgreSQL. Full feature parity for other database backends (e.g., specific data types, constraints, or unique database objects) is not explicitly guaranteed and might require explicit testing.
  Fix: Thoroughly test schema inspection results if using a database other than PostgreSQL. Refer to SQLAlchemy's dialect documentation for specifics of your chosen database.
• gotcha Views might not be fully supported or behave differently than tables, leading to unexpected results or incomplete metadata when iterating `schema.tables` or accessing `.columns` for view-like objects.
  Fix: Explicitly check for view types if your database contains views and you need to inspect them. For advanced view introspection, consider using database-specific tools or raw SQLAlchemy reflection if `schemainspect` provides insufficient detail.

Install

• pip install schemainspect Install stable version

Imports

• inspect

  from schemainspect import inspect

  The primary entry point for schema inspection.

Quickstart

This quickstart demonstrates how to connect to a database using a DSN (Data Source Name) and use `schemainspect` to retrieve and print the names of all tables and basic column details from the inspected schema. It uses an environment variable for the DSN for security.

from schemainspect import inspect
import os

# Example for PostgreSQL connection string
# Replace with your actual database URL or use an environment variable
dsn = os.environ.get("DATABASE_URL", "postgresql://user:password@localhost:5432/mydb")

# Inspect the database schema
print(f"Inspecting schema for: {dsn.split('@')[-1] if '@' in dsn else dsn}")
schema = inspect(dsn)

# Print all table names
print("\nTables found:")
if schema.tables:
    for table in schema.tables:
        print(f"  - {table.name}")
        # Optionally print columns for the first table as an example
        if table == list(schema.tables.values())[0]: # Get the first table
            for column in table.columns:
                print(f"    - Column: {column.name}, Type: {column.type}, Nullable: {column.nullable}")
else:
    print("  No tables found.")

# Access a specific table (replace 'your_table_name' with an actual table in your DB)
# if 'your_table_name' in schema.tables:
#     my_table = schema.tables['your_table_name']
#     print(f"\nDetails for table '{my_table.name}':")
#     for column in my_table.columns:
#         print(f"  Column: {column.name}, Type: {column.type}, Primary Key: {column.primary_key}")