@e9n/pi-kysely

Shared Kysely database registry for pi. Provides a single managed database connection (SQLite, PostgreSQL, or MySQL) that other extensions access via the event bus, with table-level RBAC and a built-in migration system.

Features

• Shared database — one connection pool for all extensions in a session
• Multi-driver — SQLite (default), PostgreSQL, and MySQL
• Table-level RBAC — extensions own prefixed tables and grant selective access to others
• Migration system — generate SQL diffs and apply versioned migrations with checksum integrity
• Event bus API — extensions interact via kysely:* events (no direct import needed)
• /kysely command — inspect registered databases and applied migrations at runtime

Setup / Settings

Add to ~/.pi/agent/settings.json (global) or .pi/settings.json (project):

SQLite (default)

{
  "kysely": {
    "driver": "sqlite",
    "sqlitePath": "db/kysely.db",
    "databaseName": "default",
    "autoCreateDefault": true
  }
}

PostgreSQL

{
  "kysely": {
    "driver": "postgres",
    "databaseUrl": "postgres://user:pass@localhost:5432/app"
  }
}

MySQL

{
  "kysely": {
    "driver": "mysql",
    "databaseUrl": "mysql://user:pass@localhost:3306/app"
  }
}

Key	Default	Description
driver	"sqlite"	Database driver: sqlite, postgres, or mysql.
sqlitePath	"db/kysely.db"	SQLite file path (relative to agent dir or .pi/). Supports ~.
databaseName	"default"	Name for the default registered database.
databaseUrl	—	Connection URL for postgres/mysql. Falls back to DATABASE_URL env var.
autoCreateDefault	true	Auto-create the default database on session start.

sqlitePath is resolved relative to the settings file's directory (~/.pi/agent for global, .pi/ for project). Absolute paths and ~ are supported.

Event Bus API

Other extensions communicate with pi-kysely entirely via events. No direct imports required.

Schema & Queries

Event	Description
kysely:schema:register	Apply DDL via Kysely schema builder (create tables, indexes)
kysely:query	Execute a parameterised raw SQL query

Migrations

Event	Description
kysely:migration:generate	Diff desired schema vs live DB and return migration SQL
kysely:migration:apply	Apply stored migration files (skips already-applied by name + checksum)
kysely:migration:status	List applied migrations, optionally filtered by actor

RBAC

Event	Description
kysely:grant	Grant table operations to another extension
kysely:revoke	Revoke previously granted access
kysely:grants	List current grants

Lifecycle

Event	Direction	Description
kysely:ready	emitted	Database is initialised and ready; payload contains registered databases and default driver
kysely:info	listened	Probe whether pi-kysely is available; reply callback receives the ready payload
kysely:ack	emitted	Write confirmation when a requestId is included in the payload

RBAC model

Each extension owns tables prefixed with <extensionId>__ (e.g. notes__items). Owners can grant select, insert, update, or delete on their tables to other extensions. RBAC is an in-process cooperative guard — not an OS-level sandbox.

Migration integrity

Migrations are identified by actor + name and checksummed (SHA-256, first 16 hex chars). Modifying a migration file after it has been applied causes a checksum mismatch error. Migrations are applied in sorted name order and stop on first error.

Commands

Command	Description
/kysely or /kysely status	List registered databases (name, driver, label)
/kysely close <name>	Unregister and destroy one database connection
/kysely close-all	Unregister and destroy all database connections
/kysely migrations [actor]	List applied migrations, optionally filtered by actor

Install

pi install npm:@e9n/pi-kysely

Database drivers (better-sqlite3, pg, mysql2) are bundled as dependencies.

License

MIT