Resource Identities

SQLBuild resource identities use lowercase ASCII snake_case. A name must start with a lowercase letter, end with a lowercase letter or digit, and contain only lowercase letters, digits, and underscores. Consecutive underscores are valid, so established names such as commerce__mart_v_order remain canonical.

This contract applies to models, seeds, sources, SQL and Python functions, generic and singular audits, attached audit definitions and instance names, SQL tests and parameterized cases, scenarios, SQL and Python hooks, macros, model schemas, enums, constants, materializations, providers, event exporters, loaders, tasks, assets, and checks. Private scoped declarations use exactly one leading underscore, such as _country_codes; public declarations must not use a leading underscore.

Provider classes are the one conventional derivation: when provider_name is omitted, AnalyticsApiProvider resolves to analytics_api_provider. An explicit provider_name is an authored identity and must already be canonical snake_case; SQLBuild does not normalize it.

Names derived from files use the filename stem. For example, models/daily_orders.sql defines the model identity daily_orders, while audits/generic/expression_is_true.sql defines the generic audit identity expression_is_true. Directories organize resources but do not change their names.

Physical warehouse identifiers are separate from SQLBuild resource identities. Database, schema, table, model alias, column, tag, group, and directory names retain their existing adapter-specific contracts and do not need to follow this profile.

Invalid names

Compilation fails during discovery with D016 when an authored identity is not canonical:

error[D016]: Invalid model identity 'DailyOrders' in models/DailyOrders.sql;
use snake_case 'daily_orders'

SQLBuild suggests a corrected spelling but never silently normalizes an identity. Silent normalization would make selectors, manifests, persisted execution state, and integration keys disagree about which resource ran.

Migrating existing projects

1. Rename file-derived resources and explicit name values to snake_case.
2. Update __ref, __seed, __source, function, hook, macro, audit, test, and dependency references.
3. Update selectors and external integrations, including Dagster asset/check keys, that use the old identity.
4. Compile before building.

A rename intentionally creates a new resource identity. Existing fingerprints, audit history, and other persisted state under the old name are not silently reassigned to the new resource.