Troubleshooting

Solutions to common issues when using sql-splitter.

Installation Issues

”command not found: sql-splitter”

The binary isn’t in your PATH.

Cargo install location:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/.cargo/bin:$PATH"

# Then reload
source ~/.bashrc  # or ~/.zshrc

Verify installation:

which sql-splitter

Build fails with “linker cc not found”

Missing C compiler on Linux.

# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora/RHEL
sudo dnf install gcc

# Then retry
cargo install sql-splitter

Build fails on Apple Silicon

Ensure you have Xcode command line tools:

xcode-select --install

Dialect Detection Issues

”Could not detect SQL dialect”

sql-splitter analyzes the first ~1000 lines to detect the dialect. If your dump starts with generic SQL, detection may fail.

Solution: Explicitly specify the dialect:

sql-splitter split dump.sql -o output/ --dialect mysql
sql-splitter split dump.sql -o output/ --dialect postgres

Wrong dialect detected

If auto-detection picks the wrong dialect:

# Force specific dialect
sql-splitter analyze dump.sql --dialect postgres

# Check what was detected
sql-splitter analyze dump.sql --json | jq '.dialect'

Memory Issues

”memory allocation failed” or OOM killed

This shouldn’t happen with normal sql-splitter commands (they use ~50MB constant memory). If it does:

Check for memory-intensive commands: validate and diff with FK checks can use more memory on very large files.

Disable FK checks for validation:

sql-splitter validate huge.sql --no-fk-checks

Use disk mode for query:

sql-splitter query huge.sql "SELECT ..." --disk

Limit rows per table:

sql-splitter validate huge.sql --max-rows-per-table 100000

File Issues

”No such file or directory"

# Check file exists
ls -la dump.sql

# Use absolute path
sql-splitter split /full/path/to/dump.sql -o output/

# Check permissions
chmod +r dump.sql

"Permission denied” on output

# Check output directory is writable
mkdir -p output/
chmod +w output/

# Or write to a different location
sql-splitter split dump.sql -o ~/output/

Compressed file not recognized

Ensure the file extension matches the compression format:

Format	Extension
Gzip	`.gz`
Bzip2	`.bz2`
XZ	`.xz`
Zstandard	`.zst`

# Rename if needed
mv dump.sql.gzip dump.sql.gz

# Then process
sql-splitter analyze dump.sql.gz

Parsing Issues

”0 tables found”

The dump file might not contain recognizable SQL statements.

Check file contents:

head -100 dump.sql

Common causes:

Binary format (use pg_dump -Fp for plain text)
Non-SQL file
Empty file
Encoding issues (see below)

Encoding errors or garbled output

sql-splitter expects UTF-8 encoding.

Convert encoding:

# Check current encoding
file dump.sql

# Convert from Latin-1 to UTF-8
iconv -f ISO-8859-1 -t UTF-8 dump.sql > dump-utf8.sql

# Convert from Windows-1252
iconv -f CP1252 -t UTF-8 dump.sql > dump-utf8.sql

Statements split incorrectly

Multi-line strings or unusual quoting can cause issues.

Workaround: Try a different dialect:

# PostgreSQL uses different escaping than MySQL
sql-splitter split dump.sql --dialect postgres

Validation Issues

”Duplicate primary key” false positives

If you’re validating a dump with intentional duplicates (e.g., for testing):

# Skip PK/FK checks
sql-splitter validate dump.sql --no-fk-checks

Validation too slow

PK/FK validation reads all data. Speed it up:

# Limit rows checked per table
sql-splitter validate dump.sql --max-rows-per-table 10000

# Skip FK checks entirely
sql-splitter validate dump.sql --no-fk-checks

Query Command Issues

”DuckDB error” or query fails

Common causes:

SQL syntax: DuckDB uses standard SQL, not MySQL/PostgreSQL extensions

-- MySQL LIMIT with offset
SELECT * FROM users LIMIT 10, 5  -- Won't work

-- Standard SQL
SELECT * FROM users LIMIT 5 OFFSET 10  -- Works

Column name conflicts: Use quotes for reserved words
```
SELECT "order", "user" FROM orders
```

Large file: Use disk mode

sql-splitter query huge.sql "SELECT ..." --disk

Cache issues

# Clear corrupted cache
sql-splitter query --clear-cache

# List cached databases
sql-splitter query --list-cache

Convert Issues

”Unsupported feature” warnings

Some SQL features don’t have direct equivalents across dialects:

ENUM types → Converted to VARCHAR with CHECK constraint
AUTO_INCREMENT → Converted to SERIAL (PostgreSQL) or IDENTITY (MSSQL)
Stored procedures → Skipped (out of scope)

Use --strict to fail on unsupported features instead of warning:

sql-splitter convert dump.sql --to postgres --strict

COPY statements not converted

PostgreSQL COPY FROM stdin is converted to INSERT statements:

# This works
sql-splitter convert pg_dump.sql --to mysql -o mysql.sql

If you see raw COPY blocks in output, ensure dialect was detected correctly:

sql-splitter convert pg_dump.sql --from postgres --to mysql -o mysql.sql

Sample/Shard Issues

”No rows sampled” or empty output

Check that tables exist:

sql-splitter analyze dump.sql --json | jq '.tables[].name'

Ensure required flags are set:

# sample requires --percent OR --rows
sql-splitter sample dump.sql --percent 10 -o sample.sql

# shard requires --tenant-value OR --tenant-values
sql-splitter shard dump.sql --tenant-value 123 -o tenant.sql

FK preservation issues

If related rows are missing:

# Enable FK preservation
sql-splitter sample dump.sql --percent 10 --preserve-relations -o sample.sql

# Use strict mode to catch issues
sql-splitter sample dump.sql --percent 10 --preserve-relations --strict-fk -o sample.sql

Getting Help

Verbose output

Most commands support --progress for visibility:

sql-splitter split dump.sql -o output/ --progress

JSON for debugging

Use --json for machine-readable output you can inspect:

sql-splitter analyze dump.sql --json | jq '.'

Report bugs

If you’ve found a bug:

Check existing issues
Create a new issue with:
- sql-splitter version (sql-splitter --version)
- OS and architecture
- Minimal reproduction steps
- Sample SQL (anonymized if needed)