Database Documentation

SqlDBM's Database documentation screen provides quick and simple maintenance of comments, logical names, and other metadata for project objects. Project collaborators and non-project users can also maintain this information through the Excel import/export feature.

This feature supports project properties as well as Model Governance fields.

Excel import/export feature highlights

• Allows business teams and SMEs to contribute to project documentation

• Does not require access for team members who wish to contribute (only the modeler to upload)

• Non-destructive: only DDL comments and non-DDL (metadata) properties can be changed, no risk of altering or corrupting the project

• Collaborative: a single copy of the Excel can be sent to multiple contributors, who will not overwrite each other's changes when editing separate sections

• Can be used as a deliverable project artifact and documentation

Object properties supported in Excel import/export

The following properties are editable through this functionality (most object DDL properties [i.e., column names, data types, null constraints] are also available in the export but are ignored during import):

• Logical names

• Description (this is reflected in the DDL for those databases that support it)

• Flags

• Tags (Snowflake)

• Fields (Model Governance)

• dbt properties

For structure changes on DDL properties, please refer to the "Excel upload" section on the Reverse engineering documentation linked at the end of this post.

Export XLSX

Navigate to Database documentation in SqlDBM (1) and review the available properties and DG fields (if using the Model Governance suite). You can add elements to the screen by selecting them from the right-hand panel (2) - (regardless of the selection, all fields and properties will be exported and visible in Excel).

Click the download button (3) to export the information in XLSX format.

Open the document in Excel for editing or review.

Editing metadata via Excel

The project information exported to Excel is displayed in tabular format and separated into relevant sections through Excel sheets. Some sheets are generated for all projects, and additional ones may be available if related objects exist in the related project (i.e., Tags, templates):

Default sheets available for all projects:

• Project info - includes related project name, date exported, and more

• Schemas - schemas or datasets and their properties

• Tables - consolidated list of table objects and their properties

• Columns - all project columns by table and their properties

• Constraints - project constraints (PK, FK, AK) and their properties

• Virtual relationships - includes virtual relationships and their properties

Additional sheets included dynamically where applicable in the related project:

• Column templates - column templates and descriptions from related projects

• Column template columns - template column descriptions are editable here and will be applied to tables referencing them.

• Tags (Snowflake) - tags and allowed values (defined here and assigned on other sheets to relevant project objects [i.e., tables, columns]).

• (Model Governance) Fields and dbt properties - fields and their allowed and default values (defined here and assigned on other sheets to relevant project objects [i.e., tables, columns]).

  • Note that fields have an "Applicable to" property that determines if they are applied to objects or columns. Input columns will only be generated in related sheets where applicable.

  • Also note that while field/property values (i.e., owner: 'bob' or test: -not null) can be maintained through Excel upload, their settings, found on the "Fields" sheet, (i.e., field type: dropdown or applicable to: Columns) can only be maintained on in SqlDBM.

Editable sections of the Excel are highlighted in yellow and can be redacted by hand.

Please consider the following when introducing changes:

• Changes to non-editable fields (not highlighted yellow) will be ignored, and the entire row will be skipped on upload

• DG fields and (Snowflake) tags may have allowed values defined. In some cases (i.e., drawdowns and checkboxes), the allowed values will be selectable from the Excel input help. However, this is not possible for multiselect, so be sure to check the Fields and Tags sheets to familiarize yourself with the values these properties accept.

  • Invalid entries will be skipped on upload.

Once you are finished making changes, make sure to save the document and proceed back into SqlDBM.

Import XLSX

Once changes have been made in the Excel document, navigate back to the Database documentation screen.

• Open Database Documentation Screen

• Unlock project for editing

• Click the "Upload XLSX" button

• Review the imported changes

See also

• Database documentation

• Model Governance (Fields)

• Model Governance suite (overview)

• YAML generation for dbt

• Reverse engineering

• dbt Manifest upload and project properties