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:

npm install @flatfile/plugin-convert-sql-ddl

​
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

import { listener } from "@flatfile/listener";
import { configureSpaceWithSqlDDL } from "@flatfile/plugin-convert-sql-ddl";

listener.use(
  configureSpaceWithSqlDDL({
    workbooks: [
      {
        name: "Database Import",
        source: "src/data/schema.sql",
        sheets: [
          {
            name: "Users",
            slug: "users", // Must match a table name in schema.sql
          },
          {
            name: "Products",
            slug: "products", // Must match a table name in schema.sql
          },
        ],
      },
    ],
  })
);

​
Advanced Configuration with Callback

import { listener } from "@flatfile/listener";
import { configureSpaceWithSqlDDL } from "@flatfile/plugin-convert-sql-ddl";

listener.use(
  configureSpaceWithSqlDDL(
    {
      workbooks: [
        {
          name: "Database Import",
          source: "src/data/schema.sql",
          sheets: [
            {
              name: "Users",
              slug: "users",
            },
          ],
        },
      ],
      space: {
        metadata: {
          sidebarTitle: "SQL Import Tool",
        },
      },
    },
    (event, workbookIds, tick) => {
      // This function runs after the space is configured
      console.log("Space configured successfully!");
      console.log("Created workbook IDs:", workbookIds);
      tick(100, "Configuration complete");
    }
  )
);

​
Custom Event Handler Usage

import { listener } from "@flatfile/listener";
import { configureSpaceWithSqlDDL } from "@flatfile/plugin-convert-sql-ddl";

listener.on("space:configure", async (event) => {
  const { spaceId } = event.context;
  
  const configure = configureSpaceWithSqlDDL({
    workbooks: [
      {
        name: "Customer Data",
        source: "data/my_schema.sql",
        sheets: [
          { name: "Customers", slug: "customers" },
          { name: "Orders", slug: "orders" },
        ],
      },
    ],
    space: {
      metadata: {
        theme: {
          root: {
            primaryColor: "blue"
          }
        }
      }
    }
  });
  
  await configure(listener);
});

​
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

import { listener } from "@flatfile/listener";
import { configureSpaceWithSqlDDL } from "@flatfile/plugin-convert-sql-ddl";

// Example: schema.sql contains 'users' table but not 'accounts'
listener.use(
  configureSpaceWithSqlDDL({
    workbooks: [
      {
        name: "App Data",
        source: "data/schema.sql",
        sheets: [
          {
            name: "Users",
            slug: "users", // This will succeed
          },
          {
            name: "Accounts", 
            slug: "accounts", // This will fail and be skipped
          },
        ],
      },
    ],
  })
);

​
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