Alasql cli docker / pipe issues

[ammeek]

Hi! I’m currently working on building a Docker image for AlaSQL and I’ve run into an issue where commands passed to the container aren’t being executed as expected.

From what I’ve investigated so far, it seems that Docker doesn’t attach a TTY by default when running commands through ENTRYPOINT, which changes how the CLI behaves. I tried updating the logic in alasql-cli.js, but I think there may be another underlying issue as well.

Specifically, when piping data into a query, the input is being treated as a SQL statement rather than as data. I can reproduce this behavior both inside and outside of Docker, so it doesn’t appear to be container-specific. Looking at the code in alasql-cli.js, it seems to try to read input directly, whereas I had expected file or stream reading to be handled by the standard FROM helpers such as alasql.from.TXT, which ultimately call alasql.utils.loadFile.

I may be misunderstanding the intended behavior — but it seems like the CLI is handling input differently than the query engine’s built-in file readers. I’d really appreciate any clarification on this, or advice on how best to approach making AlaSQL run reliably inside Docker. Thanks!

Steps to replicate docker issue:

1. Check out my fork of the repo
2. Run the following command to build the alasql docker image:

docker build -t alasql-test .

3. run the following command to replicate the issue:

docker run alasql-test "SELECT 1 + 1"

Expected output:

[
  {
    "1 + 1": 2
  }
]

Actual output:

No SQL to process

AlaSQL command-line utility (version 4.6.6)

Usage: alasql [options] [sql] [params]

Options:
  -v, --version  Echo AlaSQL version                                   [boolean]
  -m, --minify   Minify json output                                    [boolean]
  -f, --file     Load SQL from file                                     [string]
      --ast      Print AST instead of result                            [string]
  -h, --help     Show help                                             [boolean]

Examples:
  alasql "sql-statement"                    Run SQL statement and output result
                                            as JSON

  alasql 'value of select 2+?' 40           Outputs 42

  alasql 'select count(*) from txt()' <     Count lines in city.txt
  city.txt

  alasql 'select * into xlsx("city.xlsx")   Convert from txt to xlsx
  from txt("city.txt")'

  alasql --file file.sql France 1960        Run SQL from file with 2 parameters

Steps to replicate pipe issue:

1. Run the below command:

echo "I am test data" >> test.txt
alasql "SELECT COUNT(*) FROM txt()" < test.txt

Expected output:

[
  {
    "COUNT(*)": 1
  }
]

Actual output:

{
  "error": {
    "stack": "SyntaxError: Parse error on line 1:\nI am test data\n--^\nExpecting 'EOF', 'COMMA', 'LPAR', 'RPAR', 'END', 'ELSE', 'COLONDASH', 'GO', 'SEMICOLON', got 'LITERAL'\n    at parser.pars...",
    "message": "Parse error on line 1:\nI am test data\n--^\nExpecting 'EOF', 'COMMA', 'LPAR', 'RPAR', 'END', 'ELSE', 'COLONDASH', 'GO', 'SEMICOLON', got 'LITERAL'"
  }
}

[mathiasrw]

Sounds interesting with docker.

alasql-cli is old and probably needs a good amount of love. Looks like we broke the functionality documented in the readme. Not good.

Im not strong in docker. Asked the AlaSQLbot to help me understand this and got info from the conversation. Let me know if it helps.

---

The core of the problem:

Context	process.argv[2] contains...	Why?
Mac Terminal	SELECT 1 + 1	The shell processes and removes the quotes.
Docker ENTRYPOINT	"SELECT 1 + 1"	Docker passes the string literally, quotes included.

Scenario 1: Running "Normally" on your Mac

When you type this into your Mac's command prompt (which uses a shell like bash or zsh):

alasql "SELECT 1 + 1"

1. The Shell Intervenes: Your shell sees the command line. It recognizes the double quotes (") as special characters. Its job is to process them.
2. Quote Removal: The shell consumes the quotes, understands that they are there to group the words SELECT, 1, +, and 1 into a single argument token.
3. Execution: The shell then executes the alasql program, passing it that single argument.

Inside your Node.js script, process.argv will look like this:

[
  '/usr/local/bin/node', // The node executable
  '/path/to/alasql-cli.js', // The script being run
  'SELECT 1 + 1' // The argument. Notice: NO QUOTES.
];

The third element, process.argv[2], is the clean string SELECT 1 + 1.

---

Scenario 2: Running via Docker's ENTRYPOINT ["alasql"]

When you run this command:

docker run alasql-test "SELECT 1 + 1"

1. NO Shell Intervenes: Docker's "exec form" (ENTRYPOINT ["executable"]) does not use a shell. It performs a direct system call, which is much more literal. It has no concept of "processing" quotes.
2. Literal Passing: It takes the string you provided, "SELECT 1 + 1", and passes it verbatim, quotes and all, as a single argument to the entrypoint.

Inside your Node.js script running in the container, process.argv will look like this:

[
  '/usr/local/bin/node', // The node executable
  '/alasql/bin/alasql-cli.js', // The script being run
  '"SELECT 1 + 1"' // The argument. Notice: IT INCLUDES THE QUOTES.
];

The third element, process.argv[2], is the string "SELECT 1 + 1".

---

The problem you're seeing is a classic and subtle issue with how command-line arguments are parsed, especially when dealing with Node.js scripts and Docker entrypoints. The alasql command-line tool, like many Node.js CLIs, is often executed via a shell script wrapper (the shebang line #!/usr/bin/env node).

The most reliable way to fix this is to use a script as your entrypoint that can properly handle the arguments passed from Docker.

The Solution: Using an entrypoint.sh Script

1. Create an entrypoint.sh file:
   In the same directory as your Dockerfile (the root of your alasql repo), create a new file named entrypoint.sh.

2. Add the following content to entrypoint.sh:

   #!/bin/sh
   # This script acts as a wrapper for the alasql command.
   # The "$@" special variable expands to all the arguments passed to the script,
   # preserving quotes and spaces correctly.
   
   # Execute the alasql command with all provided arguments
   exec alasql "$@"

3. Make the script executable:
   Since you're on a Mac, run this command in your terminal to set the correct permissions. This is crucial; Docker will copy these permissions into the image.

   chmod +x entrypoint.sh

4. Modify your Dockerfile:
   Update your Dockerfile to copy and use this new script.

   FROM node:25.0.0-slim
   RUN apt-get update && apt-get install -y git && apt-get clean
   
   WORKDIR /alasql
   
   # Copy the entrypoint script first and set permissions
   COPY entrypoint.sh .
   RUN chmod +x ./entrypoint.sh
   
   # Copy the rest of the application code
   COPY . .
   
   RUN yarn install
   
   # not useing install-g as I am haveing issues with prettier.
   RUN yarn run build-only
   RUN npm uninstall alasql -g && npm install -g .
   
   # Use the script as the entrypoint
   ENTRYPOINT ["./entrypoint.sh"]

   Note: I also adjusted the COPY order slightly. It's good practice to copy things that change less often (like the entrypoint script) before things that change frequently (your source code) to better leverage Docker's caching.

Explanation: ENTRYPOINT ["executable"] vs ENTRYPOINT ["./script.sh"]

• ENTRYPOINT ["alasql"] (Exec Form): This form runs the executable directly, without a shell. Docker passes "SELECT 1 + 1" as a single argument. While this should work, some Node.js CLI tools can be finicky about how they receive and parse arguments when not run through a standard shell (sh or bash).

• ENTRYPOINT ["./entrypoint.sh"] (Wrapper Script): This is the more robust pattern. Docker runs your script, passing "SELECT 1 + 1" as an argument to it. Inside the script, "$@" is a special shell variable that expands to all command-line arguments, preserving them exactly as they were received. The exec alasql "$@" line then replaces the shell process with the alasql process, passing the arguments along perfectly. This reliably mimics how you would run the command directly in your own terminal.

[ammeek]

@mathiasrw Unfortunately, the suggestion from AlaSQLbot didn’t work for me..

I've had a look into the issue in more depth and I belive that my assumption about alasql.utils.loadFile function needing to read from the stdin rarther than the alasql-cli.js function is correct. Based on that I've raised a PR to resolve the pipe issue. While fixing the pipe issue I have also resolved my docker issue by removing the logic that depends on a TTY being attached to the terminal since we no longer expect piped data to be read at this point.

I've run the following commands in docker and on my local mashine against my change in the PR and develop and documented them below.

Command	Docker PR	Docker Dev	Local PR	Local Develop
echo "test" | alasql "SELECT COUNT(*) > 0 as Success FROM txt()"	[{"Success": true}]	TTY ERROR	[{"Success": true}]	Pipe ERROR
alasql "SELECT COUNT(*) > 0 as Success FROM txt()" < test.txt	[{"Success": true}]	TTY ERROR	[{"Success": true}]	Pipe ERROR
alasql 'select 1 as Succes'	[{"Success": true}]	TTY ERROR	[{"Success": true}]	[{"Success": true}]

I've also added some tests to cover the above cases along with some other bits of cli functionality.

[mathiasrw]

Fix released as part of v4.9.0