Command line

intosql runs the same engine as the converter on your own machine. It reads Excel, CSV, TSV, JSON and NDJSON files and MySQL or MariaDB dumps, writes SQL for PostgreSQL, MySQL, MariaDB, SQLite, SQL Server and Oracle, and can load a file straight into a database. Files are read from your disk and never uploaded.

Install#

Homebrew#

On macOS and Linux:

brew install alfonsobries/intosql/intosql

npm#

Run it once without installing, or install it globally. Both need Node 18 or newer.

npx intosql inspect ventas.xlsx
npm i -g intosql

The intosql package picks a prebuilt binary for your platform: macOS (Apple silicon and Intel), Linux (arm64 and x64) and Windows (x64).

Direct download#

Each version is published as a release named IntoSQL CLI x.y.z (tag cli-vx.y.z) at github.com/alfonsobries/intosql-releases. The release marked latest there is the desktop app, so look for the CLI release by name.

Each archive holds one file, intosql (or intosql.exe). Put it in a folder on your PATH. The Linux builds are static and run on any distribution. SHA256SUMS in the same release lists the checksum of every archive; compare it with yours:

shasum -a 256 intosql-x.y.z-aarch64-apple-darwin.tar.gz

Check the install:

intosql version

intosql 0.1.0 (contract 1)

A first conversion#

Look at the file first, then convert it:

intosql inspect ventas.csv
intosql convert ventas.csv --to postgresql -o ventas.sql

inspect shows how the file will be read and every correction the conversion makes. convert writes the script. To run the script against your database, see Loading the script.

Commands#

inspect#

Shows what a file holds: its format and encoding, where the table starts, each column's name and SQL type, every fix, any problems and a preview of the first rows. Nothing is written.

intosql inspect ventas.csv

ventas.csv: CSV (windows-1252, ";"), 5 rows, 6 columns

Columns
  1  folio    text               from "Folio"
  2  cliente  text               from "Cliente"
  3  ciudad   text               from "Ciudad"
  4  fecha    date               from "Fecha"
  5  importe  numeric(6,2) null  from "Importe"
  6  pagado   boolean            from "Pagado"

Fixes
  1. The file was written in windows-1252; it was converted to UTF-8.
  2. The header is on row 4; the rows above it were left out.
  3. Row 10 ("TOTAL") is a total, so it was left out.
  4. Leading zeros kept in "Folio": 00412 stays 00412, stored as text.
  5. 15/02/2024 proves the dates in "Fecha" are day-first, so 03/02/2024 is read as 2024-02-03.
  6. Numbers in "Importe" use a decimal comma: 1.234,50 is read as 1234.50.
  7. N/A in "Importe" read as empty (1 of 5 values).
  8. "Pagado" holds yes and no words (sí, no), stored as boolean.

Preview
  5: 00412 | Peña Muñoz | Mérida | 15/02/2024 | 1.234,50 | sí
  6: 00413 | José Ángel Ruiz | León | 03/02/2024 | 99,90 | no
  ...

The numbers on the left are column positions. --rename, --text and --exclude use them. The types are shown for PostgreSQL unless you pass --dialect. Fixes explains each correction.

inspect also takes every reading and column flag.

convert#

Converts a file into a SQL script, or into clean CSV or JSON. The output goes to standard output unless -o names a file. The summary goes to standard error, so it never mixes with the SQL.

intosql convert clientes_2024.xlsx --to mysql -o clientes_2024.sql

Converted 4 of 4 rows from clientes_2024.xlsx into clientes_2024 for MySQL.
10 fixes made; `intosql inspect clientes_2024.xlsx` lists them.

When rows can't be converted, the summary lists each one with its row number and reason, and the rest of the file is still written. Errors lists every message.

convert also takes every reading and column flag.

load#

Loads a file straight into PostgreSQL, MySQL, MariaDB or SQLite, without a script. It creates the table with the same types the script would use, loads every row, and drops the table it created if the load fails.

intosql load clientes_2024.xlsx --into postgres://ana@localhost:5432/tienda --index alta

Loaded 4 of 4 rows from clientes_2024.xlsx into clientes_2024 for PostgreSQL.
10 fixes made; `intosql inspect clientes_2024.xlsx` lists them.

Pro: Loading into PostgreSQL, MySQL and MariaDB is part of IntoSQL Pro. Loading into a SQLite file is free. See Free and Pro.

load also takes every reading and column flag. Loading the script covers each database's URL and what happens on failure.

validate#

Checks a conversion request (a JobSpec JSON file, as convert --spec and the API take it) without running it.

intosql validate pedido.json

pedido.json is a valid request.

A request with problems lists each one with its fix:

- Rows per batch must be between 1 and 100000; it is 0. Pick a number in that range. 500 suits most databases.
- The table name is empty. Type a name, or leave the field out to use the file's name.

license#

Shows the IntoSQL Pro license on this machine, or activates one.

intosql license
intosql license activate <license>

No license. Loading into a database server starts a 14-day trial.

After activation:

IntoSQL pro is active on this machine.

intosql license then shows the plan, the account and the date the license is valid until. license has no flags; activate takes the license text as its only argument.

mcp#

Serves the engine to AI agents over MCP on standard input and output. An MCP client starts this command itself; you don't run it by hand. Agents get three tools: inspect_file, convert_file (writes the output to a file) and load_file (the same rules as intosql load). Files stay on your machine.

{
    "mcpServers": {
        "intosql": {
            "command": "intosql",
            "args": ["mcp"]
        }
    }
}

mcp has no flags. MCP covers setup in each client.

version#

Prints the engine version and the version of the request and report format (the contract).

intosql version

intosql 0.1.0 (contract 1)

intosql --version prints the version alone.

Reading and column flags#

inspect, convert and load read files the same way and take these flags. Everything is detected when a flag is absent.

Positions start at 1 and match the numbers inspect prints.

intosql convert clientes_2024.xlsx --sheet Q3 --rename 3=codigo_postal --exclude 6 -o clientes.sql

Free and Pro#

Everything except loading into a database server is free: inspect, convert to every dialect, validate, mcp, and load into SQLite.

Loading into PostgreSQL, MySQL or MariaDB (with intosql load, the MCP load_file tool or the desktop app) needs IntoSQL Pro. Without a license, the first such load starts a 14-day trial on this machine:

Your 14-day IntoSQL Pro trial starts now. After it, loading into database servers needs a license (https://intosql.com/pricing); SQLite and `intosql convert` stay free.

When the trial has ended, the load stops with exit code 1 and says where to get a license.

To activate Pro:

1. Open your account dashboard. With Pro, it shows your license under "Desktop app and command line".
2. Copy the license.
3. Run intosql license activate <license>.

The license is checked on your machine, without a network call. It is saved as license in the settings folder: $INTOSQL_CONFIG_DIR when set, otherwise $XDG_CONFIG_HOME/intosql, %APPDATA%\intosql on Windows, or ~/.config/intosql. The desktop app reads the same folder, so one activation covers both. If intosql license says the saved license can't be used, copy the current one from the dashboard and activate it again.

Scripts and CI#

• Input is always a file path. Reading from standard input isn't supported.
• Output. convert writes the SQL, CSV or JSON to standard output unless -o is given, and its summary to standard error. You can pipe it into a database client:

intosql convert ventas.csv --to postgresql | psql -v ON_ERROR_STOP=1 -d tienda

• JSON. inspect --json, load --json and validate --json print machine-readable output on standard output. convert --report report.json writes the same report to a file.
• Settings folder. Set INTOSQL_CONFIG_DIR to keep the license and trial in a folder your CI controls.

Exit codes#

Rows left out don't change the exit code. To fail a build when any row is left out, check rows.rejected in the report:

intosql convert ventas.csv --to mysql -o ventas.sql --report report.json
jq -e '.rows.rejected == 0' report.json

JSON output#

load --json and convert --report write a conversion report. Shortened:

{
    "version": 1,
    "input": {
        "format": "csv",
        "encoding": "windows-1252",
        "delimiter": ";",
        "sheet": null,
        "bytes": 357
    },
    "dialect": "postgresql",
    "table": "ventas",
    "columns": [
        {
            "source_name": "Importe",
            "name": "importe",
            "sql_type": "numeric(6,2)",
            "kind": "decimal",
            "precision": 6,
            "scale": 2,
            "max_chars": null,
            "nullable": true,
            "fixes": [6, 7],
            "excluded": false,
            "as_text": false
        }
    ],
    "rows": { "read": 5, "converted": 5, "rejected": 0 },
    "fixes": [
        {
            "number": 6,
            "code": "decimal_comma_read",
            "column": "Importe",
            "row": null,
            "args": {
                "column": "Importe",
                "example": "1.234,50",
                "reading": "1234.50"
            }
        }
    ],
    "problems": [],
    "timings": { "read_ms": 0, "convert_ms": 0, "total_ms": 0 }
}

inspect --json has the same input, columns, fixes and problems, plus sheets (each sheet's name and whether it is hidden), rows as a count, and preview (row numbers and values). validate --json prints an array of problems, each with code, severity, column, row and args. The code values are the ones listed in Errors.

Crash reports#

Official builds send a report when intosql crashes on an internal error. Ordinary failures, such as a file that can't be read or a database that refuses a load, are never reported.

A report holds the error message and stack trace, the intosql version, and the operating system and processor architecture. Before it leaves your machine:

• Paths become <path>, file names become <file> and quoted values become <value>.
• Local variables and source lines are removed from every stack frame.
• The computer's name, user details and breadcrumbs are never included.

To turn reports off, set INTOSQL_NO_TELEMETRY to any value other than 0:

export INTOSQL_NO_TELEMETRY=1

The desktop app reads the same variable.