kyrosql

library0.0.5jsnpmunverified

SQL-first TypeScript code generator for PostgreSQL. Write plain SQL functions and procedures, and KyroSQL generates a fully-typed TypeScript package ready to import. Handles CREATE FUNCTION and CREATE PROCEDURE, resolves SELECT * using table schemas, and supports both npm publish and local linking. Version 0.0.5 is early alpha with no breaking changes yet. Differentiators: developer writes SQL files directly (not ORM-style code-first), generated code provides full TypeScript types and call signatures, and the generated package is a standard npm package that can be published or linked.

database

npm install kyrosql

package ↗

INSTALL

IMPORT

SIG · KYROSQL

kyrosql

databasejavascriptv0.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SqlContracts

✓ import { SqlContracts } from '@myapp/db'

✗ const SqlContracts = require('@myapp/db')

The generated package is ESM by default; named import is required.

Pool

✓ import { Pool } from 'pg'

✗ import { Pool } from '@myapp/db'

The Pool class is from the 'pg' package, not from the KyroSQL generated package.

kyrosql

✓ npm install -D kyrosql

✗ npm install kyrosql (without -D)

KyroSQL is a dev-only tool; install as devDependency.

Shows SQL-first workflow: write SQL function, define table schema, configure, build, then use generated typed function.

// SQL file: sql/functions/user/find-user-by-id.sql CREATE OR REPLACE FUNCTION find_user_by_id(p_user_id UUID) RETURNS TABLE (id UUID, name TEXT, email TEXT, created_at TIMESTAMP) LANGUAGE plpgsql AS $$ BEGIN RETURN QUERY SELECT id, name, email, created_at FROM users WHERE id = p_user_id; END; $$; // SQL file: sql/tables/users.sql CREATE TABLE users ( id UUID PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL, created_at TIMESTAMP DEFAULT NOW() ); // kyrosql.config.json { "input": "./sql", "output": "./generated", "packageName": "@myapp/db" } // Build npx kyrosql build // Use in app import { SqlContracts } from '@myapp/db'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); const user = await SqlContracts.User.findUserById({ userId: '123' }, pool); console.log(user);

Debug

Known issues

gotchaKyroSQL requires a specific folder structure: sql/tables, sql/functions, sql/procedures. Files outside these directories are ignored.

fix

Place SQL files in the correct subdirectories. Use 'kyrosql init' to generate a config and example structure.

affects: >=0.0.1

gotchaKyroSQL only supports PostgreSQL (PostgreSQL-style PL/pgSQL). Not compatible with MySQL or other databases.

fix

Use KyroSQL only with PostgreSQL projects. For other databases, consider other tools.

affects: >=0.0.1

gotchaThe generated package must be published or linked before import. Running 'kyrosql build' alone does not make the package available via npm dependency.

fix

After 'kyrosql build', run 'kyrosql publish' to publish to npm or link locally.

affects: >=0.0.1

gotchaSQL functions must have explicit RETURNS TABLE or RETURNS SETOF type. Procedures should use OUT parameters or RETURNING for results.

fix

Ensure each function returns a proper table type; procedures should include RETURNING clause or OUT parameters if output is needed.

affects: >=0.0.1

gotchaTable schema files (*.sql under sql/tables) are only used to resolve SELECT * and RETURNING *. They are not used to generate table operations or migrations.

fix

Do not expect KyroSQL to generate CRUD for tables; it only generates functions and procedures.

affects: >=0.0.1

Errors

Common errors & fixes

Cannot find module '@myapp/db'

The generated package was not published or linked after build.

fix

Run 'kyrosql publish' after 'kyrosql build'. If using local linking, ensure 'npm link' was executed and application uses 'npm link @myapp/db'.

kyrosql: command not found

KyroSQL is not installed or not in PATH.

fix

Install locally: npm install -D kyrosql, then use npx kyrosql <command>.

TypeError: SqlContracts.User.findUserById is not a function

The generated package may have been built without the required SQL files or with incorrect structure.

fix

Ensure SQL files are in correct subdirectories (sql/functions/user/find-user-by-id.sql) and rerun 'kyrosql build'.

SyntaxError at or near "RETURNS"

SQL function syntax is invalid for PostgreSQL (maybe MySQL-style function used).

fix

Use PostgreSQL-compatible syntax: e.g., CREATE OR REPLACE FUNCTION ... RETURNS TABLE (...) LANGUAGE plpgsql AS $$ ... $$;

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

pgoptionalRequired to execute generated query functions against a PostgreSQL database.

Agent activity

4 hits · last 30 days

node

Resources

packagekyrosql ↗