sql-embedder

This skill provides guidance for working with sql-embedder generated files.

About sql-embedder

sql-embedder embeds SQL into TypeScript source code. It makes developing and distributing TypeScript applications easier when you need access to SQL databases at runtime—no special permissions required. It generates statically analyzable modules.

How It Works

The tool converts .sql files into TypeScript modules (.sql.ts). Each SQL statement with a preceding comment becomes an exported constant:

books.sql       →  books.sql.ts
queries.sql     →  queries.sql.ts

Identifying Generated Files

Generated files always start with this exact comment:

// This file was generated by sql-embedder. Do not edit manually.

Critical Rule

NEVER edit .sql.ts files directly. These files are auto-generated and any manual changes will be overwritten.

If you see the generated file comment, find the corresponding .sql file (same name, without the .ts extension) and edit that instead.

Correct Workflow

1. Edit the source .sql file (e.g., books.sql)
2. Identify the generation command by checking the project’s task runner config:
   • deno.json → look for a generate task
   • package.json → look for a generate script in scripts
   • Makefile → look for a generate target
   • justfile → look for a generate recipe
3. Run the identified command to regenerate the TypeScript files

Example

To add a new query called findBooksByAuthor:

1. Edit books.sql:

   -- findBooksByAuthor finds all books by a given author.
   SELECT * FROM books WHERE author_id = ?;
   

2. Check the project config (e.g., deno.json, package.json) for the generate command

3. Run the generation command

The new query will appear in books.sql.ts as an exported constant.