Skip to main content

SQL + Jinja Templates Done Right™

Project description


SQL + Jinja Done Right™

This project is a thin wrapper around Jinja templates to help manage the generation of SQL.

In your project create a directory name sql/templates to manage your SQL files:

└── sql
    └── templates
        ├── foo.sql
        └── bar.sql

Templates are also searched from the current working directory and will have priority over files in sql/templates.

An example foo.sql might be:

SELECT '{{msg}}' as message

Then to access the SQL template use the following Python snippet:

from sqlninja import engine as sqlninja

query = sqlninja.render("foo.sql", msg="Hello World")

The resulting query would be:

SELECT 'Hello World' as message

In bar.sql lets try including foo.sql:

SELECT * FROM ({% include 'foo.sql' %}) as t1

The rendered SQL would be:

SELECT * FROM (SELECT 'Hello World' as message) as t1

Command Line Interface

The Python interface makes sense at runtime, but for development, the CLI is more convenient.

The library installs a CLI script: sql

$ sql --help
Usage: sql [OPTIONS] SRC

--template_path TEXT  Base directory where SQL templates are located.
Defaults to `sql/templates`

--help                Show this message and exit.

To see the resulting SQL we can try:

sql foo.sql msg='Hello World'

# => SELECT 'Hello World' as message


pip install sql-ninja

Or add to requirements.txt


Or add to



Docker users can pull directly from ddrscott/sql-ninja

docker run --rm -v $PWD:/app -w /app ddrscott/sql-ninja sample.sql
#            ^   ^            ^      ^                  ^
#            |   |            |      |                  |
#            |   |            |      |                  + the template
#            |   |            |      |
#            |   |            |      + the image
#            |   |            |
#            |   |            + start in /app path
#            |   |            
#            |   + volume mount current path to /app
#            |
#            + remove container when complete


Bug reports and pull requests are welcome on GitHub at


The gem is available as open-source under the terms of the MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sql-ninja-0.2.1.tar.gz (3.8 kB view hashes)

Uploaded source

Built Distribution

sql_ninja-0.2.1-py3-none-any.whl (5.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page