Skip to main content
execsql logo

Multi-DBMS SQL script processor.

CI/CD codecov Docs PyPI Python License Downloads

Overview

execsql is a toolchain for SQL scripts: write them with editor support, format them consistently, lint them without a database, and run them against nine DBMSs.

Scripts are ordinary SQL plus metacommands embedded in comments (-- !x!), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts. Other SQL tools (psql, sqlcmd, your editor) ignore the metacommand comments. Scripts that depend on those commands or on variable substitution need execsql to perform their intended work.

Command What it does Needs a database?
execsql format Normalize keywords, indentation, and SQL layout No
execsql lint Static analysis: structure, unknown metacommands, variables, targets No
execsql run Run the script against PostgreSQL, MySQL, SQLite, DuckDB, … Yes
execsql config Show every config option, its value, and the file that set it No
execsql list Metacommands, encodings, plugins, or the keyword vocabulary No
execsql init Set up a project: config file, a script with a header, pre-commit hooks No
execsql lsp Language server: lint findings, completion, hover, navigation, quick fixes and formatting in your editor No
VS Code extension Highlighting plus everything execsql lsp provides No

format and lint take files or directories.

Quick start: no database required

format and lint work on a bare .sql file, with no server and no config. Try them first:

uv tool install "execsql2[formatter]"     # or: pipx install "execsql2[formatter]"

execsql format --check scripts/   # is it formatted?
execsql format -i scripts/        # format it
execsql lint scripts/             # find problems before they cost you a run

lint reports unmatched blocks, misspelled or malformed metacommands and conditions, undefined and unused substitution variables, unreachable branches, and INCLUDE/SCRIPT targets that do not exist: the failures that otherwise surface halfway through a run against a live database:

$ execsql lint load_data.sql
load_data.sql
  1  warning  V002  variable !!site_cd!! is never used
  2  warning  I001  INCLUDE file does not exist: common/setup.sql
  3  warning  V001  undefined variable !!site_code!!

Found 3 issues in 1 file: 3 warnings (1 file checked)

V002 and V001 together point at a typo: site_cd is defined and site_code is used. Every issue has a rule code for --select and --ignore; --output-format concise prints one path:line line per issue and json feeds CI tools. The lint rules page explains each one.

execsql format also runs as a pre-commit hook, so formatting is enforced without anyone remembering to run it.

Example

This complete SQLite example needs no server, GUI or extras. Save as hello.sql:

create table sales (product text, quantity integer);
insert into sales values ('book', 2), ('book', 3), ('pen', 4);
-- !x! ASSERT ROW_COUNT_EQ(sales, 3) "Expected three input rows"
-- !x! EXPORT QUERY <<select product, sum(quantity) as quantity from sales group by product order by product;>> TO totals.csv AS CSV
execsql run --dsn sqlite:///:memory: hello.sql

It creates totals.csv with book,5 and pen,4 beneath a header, and writes execsql.log. The database is in memory; each run replaces the CSV. Your first script extends this into a CSV import/export workflow with expected output.

Installation

uv tool install execsql2                  # core: SQLite works with no extras
uv tool install "execsql2[postgres]"      # with a driver: postgres, mysql, mssql, duckdb, firebird, oracle, odbc
uv tool install "execsql2[all]"           # everything: all drivers plus all feature extras

pipx install takes the same arguments. Quote the name when it has extras (zsh reports no matches found otherwise). To call execsql from Python code, add it to that project instead: uv add "execsql2[postgres]" or pip install "execsql2[postgres]" in its virtual environment.

Feature extras cover spreadsheet and Parquet/Feather formats, keyring authentication, PostgreSQL upsert, and more. See the installation guide for the full list.

Usage

execsql run    [OPTIONS] SQL_SCRIPT [SERVER DATABASE | DATABASE_FILE]
execsql format [--check | -i] [--indent N] FILE_OR_DIR...
execsql lint   [OPTIONS] FILE_OR_DIR...
execsql config [SQL_SCRIPT] [--init] [--config FILE]
execsql list   metacommands|encodings|plugins|keywords
execsql init   [DIR] [--script NAME] [--no-script] [--no-config] [--no-pre-commit]
execsql lsp    [--check] [--log-level LEVEL] [--log-file PATH]

Examples:

execsql run -tp script.sql myserver mydb        # PostgreSQL
execsql run -tm script.sql myserver mydb        # MySQL / MariaDB
execsql run -ts script.sql myserver mydb        # SQL Server
execsql run -tl script.sql mydb.sqlite          # SQLite
execsql run -tk script.sql mydb.duckdb          # DuckDB
execsql run -to script.sql myserver myservice   # Oracle
execsql run script.sql                          # read connection from config file

Supported Databases

Flag Database Support
p PostgreSQL Supported: verified against a live server in CI
m MySQL / MariaDB Supported: verified against a live server in CI
s MS SQL Server Supported: verified against a live server in CI
l SQLite Supported: verified against real files in CI
k DuckDB Supported: verified against real files in CI
a MS Access Best effort: conditional Windows CI checks
f Firebird Best effort: not verified in CI
o Oracle Best effort: not verified in CI
d ODBC DSN Best effort: not verified in CI

Supported adapters have required real-database checks in CI. Access remains best effort: its Windows checks run when the engine installs and do not gate release builds. Firebird, Oracle and ODBC DSN have no required real-driver CI coverage. See the support table for requirements and the notice setting.

Common options

Flag Description
-t {p,m,s,l,k,a,f,o,d} Database type
-u USER Database username
-p PORT Server port
--dsn URL Connection string (e.g. postgresql://user:pass@host/db)
-n Create a new SQLite, DuckDB or PostgreSQL database if it does not exist
-c SCRIPT Execute inline SQL or metacommand string
-a VALUE Set substitution variable $ARG_x
--var NAME=VALUE Set the substitution variable !!NAME!!
-v {0,1,2,3} GUI level (0=none, 1=password/PAUSE, 2=+HALT and DB selection, 3=console)
--config FILE Load an explicit config file
--dry-run Parse the script and report commands without executing
--manifest FILE Write a JSON record of the run: files read and written, statements, errors
--debug Start in step-through debug mode (REPL pauses before each stmt)
--no-system-cmd / --no-rm-file / --no-serve Disable the SYSTEM_CMD / RM_FILE / SERVE metacommands

See the full options reference or run execsql run --help for the complete list, execsql run --ping to test a connection, execsql config to see which config files set what, and execsql list metacommands for all metacommands.

Features

Data movement

  • Import data from CSV, TSV, JSON, Excel, OpenDocument, Feather, or Parquet files into a database table.
  • Export query results in 20+ formats including CSV, TSV, JSON, JSON Lines, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
  • Copy data between databases, including across different DBMS types.

Script logic

  • Conditionally execute SQL and metacommands using IF/ELSE/ENDIF based on data values, DBMS type, or user input.
  • Loop over blocks of SQL and metacommands using LOOP/ENDLOOP; include or chain scripts with INCLUDE and SCRIPT.
  • Use substitution variables (SUB, $ARG_x, built-in variables like $date_tag) to parameterize scripts.
  • Validate data with ASSERT: halt the script with a clear error message if a condition is false (ideal for CI pipelines).

Interaction & observability

  • Display query results in a GUI dialog; optionally prompt the user to select a row, enter a value, or submit a form.
  • Write status messages or tabular output to the console or a file during execution.
  • Automatically log each run, recording databases used, scripts executed, and user responses.

Extensibility

  • Extend with custom metacommands, exporters, and importers via the plugin system.

Library API

Install execsql2 in your Python project, then call run:

from execsql import run

result = run(
    sql="CREATE TABLE t (id INTEGER);\nINSERT INTO t VALUES (1);",
    dsn="sqlite:///:memory:",
)
result.raise_on_error()
print(result.success)  # True

The Python API guide covers script files, variables, supplied connections, result/error handling and setup exceptions. Each call uses its own runtime context; the caller manages a supplied connection's lifetime.

Formatting Scripts

The execsql format command normalizes execsql script files: it uppercases metacommand keywords, corrects block indentation, and optionally reformats SQL via sqlglot. The metacommand / indent / keyword reformatting is built into execsql2; SQL reformatting requires the [formatter] extra (or pass --no-sql to skip it):

# Install with the SQL-reformatting extra
uv tool install "execsql2[formatter]"

# Format files in place
execsql format --in-place scripts/

# Check formatting without writing (useful in CI)
execsql format --check scripts/

# Run the formatter without sqlglot: keyword/indent normalization only
execsql format --no-sql --in-place scripts/

execsql format and execsql lint are also available as pre-commit hooks. The format hook id is unchanged, so existing configs keep working:

repos:
  - repo: https://github.com/geocoug/execsql
    rev: v2.40.0
    hooks:
      - id: execsql-format
      - id: execsql-lint

The format hook rewrites *.sql files in place by default; the lint hook fails the commit when a script has a lint error. See the formatter documentation for --check, --indent, and other options.

VS Code

Install the language server, then download the extension separately:

uv tool install "execsql2[lsp]"
execsql lsp --check
curl -fL --output execsql-syntax.vsix \
  https://github.com/geocoug/execsql/releases/latest/download/execsql-syntax.vsix
code --install-extension ./execsql-syntax.vsix

Run the download and install commands in the same directory. The last command reads a local file; it fails with ENOENT if the file is missing. Alternatively, download the VSIX from the current release, then use VS Code's Extensions → … → Install from VSIX….

If you use other extras, retain them in the install command, for example "execsql2[postgres,lsp]". See VS Code setup and troubleshooting or other editor setup.

Templates

The templates/ directory in this repository includes ready-to-use execsql scripts, tested against live databases in CI; see the Templates documentation. (execsql config --init writes an annotated configuration file.)

  • Upsert scripts (md_upsert.sql, ss_upsert.sql): Perform merge/upsert operations on multiple tables simultaneously, respecting foreign key order, for MySQL/MariaDB and SQL Server. On PostgreSQL, use the PG_UPSERT metacommand.
  • Comparison scripts (pg_compare.sql, md_compare.sql, ss_compare.sql): Compare staging and base tables across multiple dimensions.
  • Glossary scripts (pg_glossary.sql, md_glossary.sql, ss_glossary.sql): Produce a glossary of column names and definitions to accompany a database export.
  • script_template.sql: A framework for new scripts with sections for configuration, logging, and error reporting.

Documentation

Full documentation, including a complete metacommand reference and examples grouped by task, is at execsql2.readthedocs.io.

Copyright (c) 2007-2025 R.Dreas Nielsen

Copyright (c) 2026-present Caleb Grant

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Metadata

Release files for execsql2 2.40.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for execsql2 2.40.0
File Size Uploaded Provenance Actions
execsql2-2.40.0.tar.gz 2.7 MB With provenance Details for execsql2-2.40.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for execsql2 2.40.0
File Interpreter ABI Platform Actions
execsql2-2.40.0-py3-none-any.whl Python 3 none any Details for execsql2-2.40.0-py3-none-any.whl

Total release size: 3.3 MB

Release files / execsql2-2.40.0.tar.gz

Download URL execsql2-2.40.0.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
7f586b0b1f07e3c2906133ac15d0d0c169e351ced8fa5f244ea0848b4bb9fa1d
BLAKE2b-256 checksum
How to use checksums
4d116630104d8629af0572293c161d8de35827fb3abcf4fd18d1ca6a959c997c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / execsql2-2.40.0-py3-none-any.whl

Download URL execsql2-2.40.0-py3-none-any.whl
Size 616.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a7d903dcc3e50264ed451a0b11eddcb3751276a49ee5331f66275c9d25939b5
BLAKE2b-256 checksum
How to use checksums
be6163fae3349689eb7fe169e3a7f6581b8398605f4edac57b5a575fac3eb01d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for execsql2 2.40.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for execsql2-2.40.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.40.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page