Skip to content
IntoSQL home
Convert a file

API

Conversion spec

Every field of the IntoSQL conversion spec, the request that says how a file is read and what is written, the same in the API, the CLI and MCP.

View as Markdown

The spec is the whole request for a conversion: how to read the file, which database to write for, and what to change about single columns. It is the same object everywhere IntoSQL runs: the API takes it in spec, intosql validate checks it, and the converter on the site builds it from its options.

Every field but the database has a default that suits most files, so the API takes a spec that only names it:

JSON
{ "output": { "dialect": "mysql" } }

The API fills in the rest and the conversion keeps the whole spec, which reads like this:

JSON
{
    "version": 1,
    "input": {},
    "output": {
        "format": "sql",
        "dialect": "mysql",
        "create_table": true,
        "column_names": "snake_case",
        "style": "inserts",
        "batch_rows": 500
    },
    "inference": {
        "sample_rows": 10000,
        "date_order": "auto",
        "keep_leading_zeros": true
    },
    "columns": []
}

A spec that changes more, for a semicolon CSV from Mexico loaded into an existing PostgreSQL table, with one column renamed and one left out:

JSON
{
    "version": 1,
    "input": { "delimiter": ";", "encoding": "windows-1252", "header_row": 2 },
    "output": {
        "format": "sql",
        "dialect": "postgresql",
        "table": "ventas",
        "schema": "staging",
        "create_table": false,
        "column_names": "snake_case",
        "style": "inserts",
        "batch_rows": 1000
    },
    "inference": {
        "sample_rows": 10000,
        "date_order": "day_first",
        "keep_leading_zeros": true,
        "locale": "es-MX"
    },
    "columns": [
        { "index": 0, "name": "folio" },
        { "index": 5, "exclude": true }
    ]
}

The spec

A conversion request, the same for the browser, the CLI, the API and MCP.

Field Type Description
version integer Required.
input object Required. How to read the input.
output object Required. What to write.
inference object Required. How column types are inferred.
columns array of objects Changes to single columns; every other column is written as detected.

input

How to read the input.

Field Type Description
format one of xlsx, xls, xlsb, ods, csv, tsv, json, ndjson, sql_dump Detected from the content when absent.
encoding string or null An encoding label such as windows-1252; detected when absent.
delimiter string or null For delimited text; detected when absent.
sheet string or null For spreadsheets; the first sheet when absent.
header_row integer or null 1-based row holding the column names; detected when absent.

output

What to write.

Field Type Description
format one of sql, csv, json Required. What a conversion writes.
dialect one of postgresql, mysql, mariadb, sqlite, sql_server, oracle Required. Decides names and types, for every format.
table string or null Derived from the file or sheet name when absent.
schema string or null
create_table boolean Required.
column_names one of snake_case, as_written Required. How column names are written.
style one of inserts, bulk Required. How rows are written.
batch_rows integer Required. Rows per statement or bulk batch.

inference

How column types are inferred.

Field Type Description
sample_rows integer Required. Rows read before the types are decided.
date_order one of day_first, month_first, year_first, auto Required. How ambiguous dates such as 03/02/2024 are read.
keep_leading_zeros boolean Required. Values such as 00127 stay text so the zeros survive.
locale string or null A BCP 47 tag such as es-MX. Decides what the data can't: ambiguous dates and decimal separators. Month-first and decimal point when absent.

columns

What to do with one column of the file, found by its position.

Field Type Description
index integer Required. 0-based position of the column in the file.
name string or null The name to write instead of the one derived from the header.
as_text boolean Keep every value as written: the column becomes text.
exclude boolean Leave the column out of the output.