SQL DDL to Flatfile Blueprint Converter
Automatically create Flatfile Blueprints from SQL Data Definition Language (DDL) files to streamline database schema imports.
The SQL DDL Converter plugin automates the creation of a Flatfile Blueprint from a SQL Data Definition Language (DDL) file. Its primary purpose is to streamline the setup of a Flatfile Space by translating existing database schemas directly into Flatfile Workbooks and Sheets.
The plugin reads a provided SQL file (e.g., from a CREATE TABLE
script), parses it to identify table structures, and converts each table into a corresponding Sheet configuration with appropriate fields. This is ideal for use cases where a data import process needs to match an existing database schema, saving significant manual configuration time. It is designed to be used in a server-side listener, typically on the space:configure
event.
Installation
Install the plugin using npm:
Configuration & Parameters
The plugin is configured through the setupFactory
object passed to the configureSpaceWithSqlDDL
function.
setupFactory: SqlSetupFactory (required)
The main configuration object containing:
workbooks: PartialWorkbookConfig[] (required)
An array of workbook configurations to create in the Space.
Each PartialWorkbookConfig
object contains:
- name (string): The display name of the Workbook
- source (string, required): The relative file path to the SQL DDL file (relative to project root)
- sheets (PartialSheetConfig[], required): An array of sheet configurations
Each PartialSheetConfig
object contains:
- name (string): The display name of the Sheet
- slug (string, required): The identifier for the sheet that MUST exactly match the table name from the SQL DDL file
space (object, optional)
An object containing additional configuration for the Space itself, such as metadata. Follows the structure of Flatfile.spaces.SpaceConfig
.
Default Behavior
The plugin has no default configuration and requires the setupFactory
object to be fully defined. It will:
- Read the file specified in the
source
property - Parse it as MySQL DDL
- Map each table to a sheet configuration where the table name matches the sheet’s
slug
- Log errors to console and skip sheets if the
slug
doesn’t correspond to any table found in the SQL file - Continue processing remaining valid sheets
Usage Examples
Basic Usage
Advanced Configuration with Callback
Custom Event Handler Usage
Troubleshooting
Schema Not Found Error
If a sheet’s slug
doesn’t match any table in the SQL file, you’ll see a console error:
Schema not found for table name accounts
Solution: Ensure the slug
property exactly matches the table name in your SQL DDL file.
File Not Found Error
If the SQL file specified in the source
property cannot be read, a hard error will be thrown.
Solution:
- Verify the file path is correct and relative to your project root
- Ensure the file exists and the process has read permissions
- Check that the file contains valid MySQL DDL syntax
Example Error Handling
Notes
Important Considerations
- Server-Side Only: This plugin must be deployed in a server-side listener environment as it requires file system access to read SQL files
- File Path: The
source
property must be a file path relative to the project’s root directory - SQL Dialect: Currently only supports MySQL-compatible DDL syntax due to the hardcoded parser configuration
- Exact Matching: The
slug
property must exactly match table names in your SQL DDL file for proper field generation - Automatic Constraints: The plugin automatically identifies
NOT NULL
columns and other constraints from DDL and translates them into Flatfile field constraints - Bundled Dependencies: Uses
sql-ddl-to-json-schema
and@flatfile/plugin-convert-json-schema
internally (no separate installation required)
Default Behavior
- Reads and parses SQL files as MySQL DDL
- Maps tables to sheets based on exact slug matching
- Logs errors for unmatched slugs but continues processing valid sheets
- Automatically applies field constraints based on SQL column definitions
- Requires fully defined configuration with no built-in defaults