{"id":41999,"library":"sqlfu","title":"sqlfu","description":"SQL-first toolkit for SQLite (v0.0.3-15, pre-release, active development). Provides a client, migrator, diff engine, TypeScript type generator, formatter, and admin UI. Designed for teams who prefer SQL as the source of truth over ORM abstractions. Key differentiators: SQL files as schema and migrations, TypeScript generation from .sql queries, agent-friendly tooling, and an admin UI. Requires Node >=22 and peer deps @effect/sql, effect, better-auth, and @sqlfu/ui. Rolling releases with high churn; breaking changes expected.","status":"active","version":"0.0.3-15","language":"javascript","source_language":"en","source_url":"https://github.com/mmkal/sqlfu","tags":["javascript"],"install":[{"cmd":"npm install sqlfu","lang":"bash","label":"npm"},{"cmd":"yarn add sqlfu","lang":"bash","label":"yarn"},{"cmd":"pnpm add sqlfu","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime client for SQLite connections and queries.","package":"@effect/sql","optional":false},{"reason":"Effect-TS ecosystem for typed errors, observability, and outbox pattern.","package":"effect","optional":false},{"reason":"Authentication for the admin UI.","package":"better-auth","optional":true},{"reason":"Admin UI package for browser-based inspection.","package":"@sqlfu/ui","optional":true}],"imports":[{"note":"ESM-only package (Node>=22). CommonJS require will fail.","wrong":"const Client = require('sqlfu')","symbol":"Client","correct":"import { Client } from 'sqlfu'"},{"note":"createClient is exported from the root package, not a subpath.","wrong":"import { createClient } from 'sqlfu/client'","symbol":"createClient","correct":"import { createClient } from 'sqlfu'"},{"note":"All public APIs are re-exported from the main 'sqlfu' entry point.","wrong":"import { draftMigration } from 'sqlfu/migrator'","symbol":"draftMigration","correct":"import { draftMigration } from 'sqlfu'"},{"note":"Returns an Effect that processes .sql files. Use with Effect.runSync or runPromise.","wrong":null,"symbol":"typegen","correct":"import { typegen } from 'sqlfu'"}],"quickstart":{"code":"import { createClient, typegen } from 'sqlfu'\nimport { SqliteClient } from '@effect/sql-sqlite-node'\n\n// Create a client using @effect/sql's SqliteClient\nconst sqlite = SqliteClient.make({\n  filename: ':memory:',\n})\n\n// Create a sqlfu client wrapper\nconst client = createClient(sqlite)\n\n// Run a raw SQL query\nconst rows = await client.query('SELECT 1 AS value')\nconsole.log(rows) // [{ value: 1 }]\n\n// Type generation from .sql files\n// Assumes you have a 'sql/my-query.sql' file\nconst genResult = await typegen({\n  sourceDir: './sql',\n})()\nconsole.log(genResult) // Generated TypeScript types\n\n// Existing client operations\nawait client.execute('CREATE TABLE test (id INTEGER PRIMARY KEY)')\nawait client.execute('INSERT INTO test VALUES (1)')\nconst result = await client.query('SELECT * FROM test')\nconsole.log(result) // [{ id: 1 }]","lang":"typescript","description":"Creates a SQLite client, runs queries, and demonstrates type generation from SQL files."},"warnings":[{"fix":"Pin to exact version and follow changelog on GitHub.","message":"API surface is unstable (pre-release v0.0.x). Breaking changes occur frequently without deprecation warnings.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Ensure package.json includes @effect/sql@^0.51.1.","message":"Peer dependency @effect/sql must be exactly ^0.51.1 or compatible range. Incompatible versions cause runtime errors in query execution.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Use Node 22+ with ESM (type:module in package.json or .mjs files).","message":"Requires Node >=22 (ESM only). CommonJS projects cannot import this package.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Install all peer deps: npm install @effect/sql better-auth @sqlfu/ui","message":"Admin UI requires better-auth and @sqlfu/ui as peer deps. Skipping them causes missing peer warnings and potential runtime errors.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Avoid reliance on outbox feature for production usage.","message":"The experimental outbox pattern may be removed or reworked in future versions.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'22':64 'abstract':40 'activ':12 'admin':25,60 'agent':55 'agent-friend':54 'auth':72 'better':71 'better-auth':70 'break':80 'chang':81 'churn':79 'client':16 'dep':67 'design':27 'develop':13 'diff':18 'differenti':42 'effect':69 'effect/sql':68 'engin':19 'expect':82 'file':44 'first':4 'formatt':23 'friend':56 'generat':22,50 'high':78 'javascript':83 'key':41 'migrat':17,48 'node':63 'orm':39 'peer':66 'pre':10 'pre-releas':9 'prefer':31 'provid':14 'queri':53 'releas':11,76 'requir':62 'roll':75 'schema':46 'sourc':35 'sql':3,32,43,52 'sql-first':2 'sqlfu':1 'sqlfu/ui':74 'sqlite':7 'team':29 'tool':57 'toolkit':5 'truth':37 'type':21 'typescript':20,49 'ui':26,61 'v0.0.3-15':8","created_at":"2026-06-04T18:55:08.090101+00:00","updated_at":"2026-06-04T18:55:08.090101+00:00","problems":[{"fix":"Switch to ESM (type:module in package.json) and upgrade Node to 22+.","cause":"Package is ESM-only but project is using CommonJS (require) or Node version <22.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'sqlfu'"},{"fix":"Run npm install @effect/sql@^0.51.1 effect@^3.21.2","cause":"Missing peer dependencies.","error":"Cannot find module '@effect/sql' or 'effect'"},{"fix":"Use createClient(yourDatabaseAdapter) where yourDatabaseAdapter matches the @effect/sql interface.","cause":"Client created with adapter factory but adapter not properly wrapped.","error":"TypeError: client.query is not a function"},{"fix":"Use dynamic import() or switch project to ESM.","cause":"Using CommonJS require() to import sqlfu which is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/mmkal/sqlfu#readme","github":"https://github.com/mmkal/sqlfu","docs":null,"changelog":null,"pypi":null,"npm":"sqlfu","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}