Scriptella

Scriptella is a lightweight, XML-driven ETL and database migration tool for Java. Use SQL and scripting languages directly to move and transform data without a proprietary transformation language or graphical designer.

Why Scriptella?

• SQL-first: Work in the language best suited to each data source instead of learning a proprietary transformation language.
• Lightweight: Run jobs from a single configuration file without a server or graphical designer.
• Automation-friendly: Keep migrations and data jobs in version control and run them locally, in build pipelines, or on a schedule.

Project status

The latest release is Scriptella 1.7.0 (Java 17 baseline).

Scriptella 1.7.0 is available from GitHub Releases and Maven Central.

See the changelog for the release details and compatibility changes.

Requirements

Version	Java
Scriptella 1.7.0	Java 17
Scriptella 1.3 (Java 8 compatibility release)	Java 8

Getting Scriptella

Binary distribution

Download a published release from GitHub Releases or https://scriptella.org/download.html.

Unzip the binary distribution, change to the extracted directory, and run an ETL file:

java -jar scriptella.jar path/to/file.etl.xml

Add JDBC drivers and other provider JARs with the connection classpath attribute as needed. See the tutorial and reference.

Experimental curl installer

Install the latest stable release with curl:

curl -fsSL https://scriptella.org/install.sh | sh

The installer places Scriptella under ${HOME}/.local/scriptella. It either adds ${HOME}/.local/scriptella/bin to an existing startup file or prints the exact PATH command to add manually. The guaranteed command is the packaged scriptella.sh launcher:

scriptella.sh path/to/file.etl.xml

The installer does not install Java; Scriptella requires Java 17 or newer. When the installer updates a startup file, start a new shell or reload that file before using scriptella.sh. Manual ZIP installation and java -jar scriptella.jar remain available above.

Direct SQL execution

Scriptella can execute a SQL file directly against a JDBC connection without ETL XML:

scriptella.sh execute-sql --url jdbc:postgresql://localhost/app --user app schema.sql

See the direct SQL guide for driver setup, properties, literal mode, and CLI options. For embedded execution, see Executing Scriptella from Java.

Quick start

Create people.csv next to scriptella.jar:

id,name
1,Ada
2,Grace

Then create csv-to-sql.etl.xml in the same directory:

<!DOCTYPE etl SYSTEM "http://scriptella.org/dtd/etl.dtd">
<etl>
    <connection id="input" driver="csv" url="people.csv"/>
    <connection id="output" driver="text" url="load.sql"/>

    <query connection-id="input">
        <script connection-id="output">
            INSERT INTO people (id, name) VALUES ($id, '$name');
        </script>
    </query>
</etl>

The flow is source row to nested action:

1. <query connection-id="input"> asks the CSV connection for rows. The CSV driver treats the first line as headers and emits one row for each remaining line.
2. The nested <script connection-id="output"> runs once for every emitted row. Its connection-id selects the destination; nesting supplies the current source row.
3. $id and $name expand values from that current row. This example writes text, so substitution is intentional. When the destination is JDBC, use ?id and ?name parameters to bind SQL values safely.

Run it from that directory:

java -jar scriptella.jar csv-to-sql.etl.xml
cat load.sql

The generated load.sql contains one INSERT statement per CSV data row. No database or JDBC driver is required.

JSON and JSON Lines

The JSON driver adds streaming JSON input and typed JSON object templates for output, including JSON Lines. See the JSON guide for JSON-to-database, database-to-JSON and JSON transformations. They are bundled in the examples archive built with ant examples.

First migration

The real power comes from nesting a target <script> inside a source <query> to transform or copy each row. For a complete MySQL-to-PostgreSQL example that writes directly to a database with JDBC parameter binding, see docs/first-migration.md. The tutorial has additional database and file integration examples.

Modules and drivers

Scriptella is split into a core module and optional provider modules. scriptella-core contains the ETL engine, service-provider API, and generic JDBC bridge. It can use any vendor JDBC driver supplied by the application; the vendor's JAR is not part of Scriptella core.

scriptella-drivers contains an opinionated collection of built-in adapters, including database aliases, CSV, text, Velocity, Spring, mail, and scripting providers. It depends on scriptella-core, but core does not depend on the drivers module. Third-party drivers and providers can be supplied separately through a connection's classpath attribute.

Maven coordinates

Published artifacts use group ID org.scriptella (from 1.2 onward). Example for the core module:

<dependency>
  <groupId>org.scriptella</groupId>
  <artifactId>scriptella-core</artifactId>
  <version>1.7.0</version>
</dependency>

Drivers and tools modules follow the same version. For most Maven-based JDBC usage, scriptella-core is sufficient together with your database's JDBC driver. Add scriptella-drivers when you need Scriptella's built-in aliases or specialized providers, or use the binary distribution/all-in-one JAR for the assembled product. Optional provider runtime libraries may still need to be supplied separately; see the provider documentation.

Build from source

Requires Java 17+ and Maven 3.6+:

mvn clean install

Release packaging uses Ant 1.10.17 and is validated on JDK 17 and JDK 25; artifacts remain Java 17-compatible (--release 17).

Documentation

• Website: https://scriptella.org
• Reference: https://scriptella.org/reference/
• Executing from Java: docs/java-execution.md
• API docs: https://scriptella.org/docs/api/
• Core database compatibility and validation targets: docs/core-database-compatibility.md
• Public real-database compatibility tests powered by Testcontainers: scriptella-testcontainers
• Batching and insert performance: docs/batching-performance.md
• Connection lifetime and early commit/close: docs/connection-lifecycle.md
• CSV import benchmarks: scriptella-benchmarks
• Command-line usage contract and automation templates: docs/cli-usage.md
• Open Knowledge Format: curated machine-readable knowledge about Scriptella's configuration, execution model, providers, JDBC compatibility, CLI, and security: okf/index.md
• Release history: CHANGELOG.md
• Maintainer guide: docs/MAINTAINING.md

Distribution archives include these Markdown guides under docs/, alongside any generated documentation.

Support and contributions

• Bugs and features: GitHub Issues
• Discussion: GitHub Discussions
• Support: scriptella.org/support.html; commercial inquiries: [email protected]

Pull requests and well-scoped issue reports for compatibility, correctness, and maintenance work are welcome. Broad feature development is not currently the project focus.

License

Scriptella is licensed under the Apache License 2.0.