Schema Naming Configuration¶

The nexus package uses a custom generate_schema_name macro to provide flexible and consistent schema naming across different data warehouses and environments.

Overview¶

The schema naming system distinguishes between different types of models:

Core nexus models: Use nexus_{{ target.name }} schema naming
Template source models: Use default dbt schema naming (same as client models)
Client models: Use standard dbt schema naming

Default Behavior¶

Core Nexus Models¶

Core nexus models (in nexus-models/ directory) build into schemas based on the target environment:

Dev target: nexus_dev
Prod target: nexus_prod
Other targets: nexus_{{ target.name }}

Template Source Models¶

Template source models (in sources/ directory) use the default dbt schema naming:

Uses the schema value from your dbt profile configuration
Same behavior as your client models
Example: development schema for dev target

Client Models¶

Your project's models use standard dbt schema naming:

Uses the schema value from your dbt profile configuration
Follows standard dbt conventions

Custom Schema Override¶

You can override the default nexus schema naming using variables:

Configuration in dbt_project.yml¶

# dbt_project.yml
vars:
  nexus_schema_dev: "my_custom_dev_schema"
  nexus_schema_prod: "my_custom_prod_schema"

Command Line Override¶

# Override dev schema
dbt run --vars '{"nexus_schema_dev": "custom_dev_schema"}'

# Override prod schema
dbt run --vars '{"nexus_schema_prod": "custom_prod_schema"}'

# Override both
dbt run --vars '{"nexus_schema_dev": "custom_dev", "nexus_schema_prod": "custom_prod"}'

Cross-Warehouse Compatibility¶

The schema naming works consistently across all supported data warehouses:

BigQuery¶

Project: Uses target.project from profile
Dataset: Uses the generated schema name
Table: Uses the model name
Format: project.dataset.table

Snowflake¶

Database: Uses target.database from profile
Schema: Uses the generated schema name
Table: Uses the model name
Format: database.schema.table

PostgreSQL¶

Database: Uses target.database from profile
Schema: Uses the generated schema name
Table: Uses the model name
Format: database.schema.table

Schema Naming Priority¶

The macro follows this priority order for nexus models:

Custom variables (nexus_schema_dev or nexus_schema_prod)
Default nexus naming (nexus_{{ target.name }})
Custom schema name (if specified in model config)

For non-nexus models, it uses standard dbt behavior:

Custom schema name (if specified in model config)
Default schema (from profile configuration)

Examples¶

Default Configuration¶

# profiles.yml
slide_rule_tech:
  outputs:
    dev:
      schema: development
    prod:
      schema: production

Result:

Core nexus models: nexus_dev, nexus_prod
Template sources: development, production
Client models: development, production

Custom Schema Override¶

# dbt_project.yml
vars:
  nexus_schema_dev: "analytics_dev"
  nexus_schema_prod: "analytics_prod"

Result:

Core nexus models: analytics_dev, analytics_prod
Template sources: development, production (unchanged)
Client models: development, production (unchanged)

Mixed Configuration¶

# dbt_project.yml
vars:
  nexus_schema_dev: "analytics_dev"
  # nexus_schema_prod not set

Result:

Core nexus models: analytics_dev (dev), nexus_prod (prod)
Template sources: development, production
Client models: development, production

Troubleshooting¶

Schema Not Updating¶

If schema names aren't updating as expected:

Check macro location: Ensure generate_schema_name.sql is in your project's macros/ directory
Verify variable syntax: Use correct YAML syntax for variables
Check target name: Ensure your target name matches the variable name (nexus_schema_dev for dev target)
Clear dbt cache: Run dbt clean and dbt deps to refresh

Cross-Warehouse Issues¶

If schemas aren't working across different warehouses:

Check profile configuration: Ensure database/project names are correct
Verify permissions: Ensure the service account/user has access to create schemas
Test with simple models: Start with basic models to isolate issues

Template Sources Using Wrong Schema¶

If template sources are using nexus schema instead of default:

Check file path: Ensure models are in sources/ directory
Verify macro logic: The macro checks for 'sources/' in the file path
Update macro: Ensure the latest version of the macro is being used

Migration Guide¶

From Previous Versions¶

If you're upgrading from a version without custom schema naming:

No changes needed: Default behavior remains the same
Optional customization: Add variables to customize schema names
Test thoroughly: Verify schema names in your target environment

Adding Custom Schema Names¶

To add custom schema names to an existing project:

Add variables to your dbt_project.yml
Test in dev environment first
Update references if any models reference specific schema names
Deploy to prod once verified

Best Practices¶

Schema Naming Conventions¶

Use descriptive names: Make schema names clear and meaningful
Include environment: Always include environment in schema names
Be consistent: Use the same naming pattern across all environments
Avoid conflicts: Ensure schema names don't conflict with existing schemas

Environment Management¶

Separate dev/prod: Use different schema names for different environments
Use variables: Leverage dbt variables for environment-specific configuration
Document changes: Keep track of schema naming decisions and changes

Performance Considerations¶

Schema creation: Be aware that creating new schemas may require additional permissions
Cross-schema queries: Consider performance implications of queries across schemas
Indexing: Ensure proper indexing for cross-schema references