Port bun-mariadb conventions: init globals, db handler, split schema sync
- init() loads config, schema and the SQLite client once into globals - all CRUD queries go through lib/db-handler.ts (optional per-call config) - split db-schema-manager.ts into lib/schema/* with FK-aware table ordering - add bun:test tests for schema ordering, FK constraints and schema sync - config/schema files can be .ts/.js/.json/.yaml/.yml; db_schema_file_name is now optional (defaults to schema.* in db_dir) - add export/import commands (database snapshot + schema archives) - package exports map, type re-exports, hardened publish.sh - validate table name in delete Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Claude Opus 5.5
@@ -19,6 +19,8 @@ A schema-driven SQLite manager for [Bun](https://bun.sh), featuring automatic sc
|
||||
- [`typedef`](#typedef--generate-typescript-types-only)
|
||||
- [`backup`](#backup--back-up-the-database)
|
||||
- [`restore`](#restore--restore-the-database-from-a-backup)
|
||||
- [`export`](#export--portable-database--schema-archive)
|
||||
- [`import`](#import--database-file-sql-script-or-export-archive)
|
||||
- [CRUD API](#crud-api)
|
||||
- [Select](#select)
|
||||
- [Insert](#insert)
|
||||
@@ -47,7 +49,7 @@ A schema-driven SQLite manager for [Bun](https://bun.sh), featuring automatic sc
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This works for just `bun`, so `bun` should be installed.
|
||||
This works for just `bun`, so `bun` (>= 1.3) should be installed.
|
||||
|
||||
---
|
||||
|
||||
@@ -92,7 +94,6 @@ import type { BunSQLiteConfig } from "@moduletrace/bun-sqlite";
|
||||
|
||||
const config: BunSQLiteConfig = {
|
||||
db_name: "my-app.db",
|
||||
db_schema_file_name: "schema.ts",
|
||||
db_dir: "./db", // optional: where to store the db file
|
||||
db_backup_dir: ".backups", // optional: name of backups directory. Relative to the db dir.
|
||||
typedef_file_path: "./db/types/db.ts", // optional: where to write generated types
|
||||
@@ -103,7 +104,7 @@ export default config;
|
||||
|
||||
### 2. Define your schema
|
||||
|
||||
Create `./db/schema.ts` (matching `db_schema_file_name` above):
|
||||
Create `./db/schema.ts` in `db_dir` (or `schema.js`, `schema.json`, `schema.yaml`, `schema.yml`):
|
||||
|
||||
```ts
|
||||
import type { BUN_SQLITE_DatabaseSchemaType } from "@moduletrace/bun-sqlite";
|
||||
@@ -163,16 +164,18 @@ await BunSQLite.delete({ table: "users", targetId: 1 });
|
||||
|
||||
## Configuration
|
||||
|
||||
The config file must be named `bun-sqlite.config.ts` and placed at the root of your project.
|
||||
The config file is `bun-sqlite.config.ts` at the root of your project. `bun-sqlite.config.js`, `.json`, `.yaml` and `.yml` also work; keep only one. `.ts`/`.js` files must `export default` the config.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------ |
|
||||
| `db_name` | `string` | Yes | Filename for the SQLite database (e.g. `"app.db"`) |
|
||||
| `db_schema_file_name` | `string` | Yes | Filename of the schema file relative to `db_dir` (or root if `db_dir` is not set) |
|
||||
| `db_schema_file_name` | `string` | No | Schema filename relative to `db_dir`. Defaults to `schema.ts\|js\|json\|yaml\|yml` in `db_dir` |
|
||||
| `db_backup_dir` | `string` | No | Directory for database backups, relative to `db_dir` |
|
||||
| `db_dir` | `string` | No | Root directory for the database file and schema. Defaults to project root |
|
||||
| `typedef_file_path` | `string` | No | Output path for generated TypeScript types, relative to project root |
|
||||
| `max_backups` | `number` | No | Maximum number of backup files to keep. Oldest are deleted automatically. Defaults to `10` |
|
||||
| `max_exports` | `number` | No | Maximum number of archives kept in `{db_dir}/.exports` by `export`. Defaults to `10` |
|
||||
| `wal_mode` | `boolean`| No | Enable SQLite `WAL` journal mode |
|
||||
|
||||
---
|
||||
|
||||
@@ -334,6 +337,43 @@ bunx bun-sqlite restore
|
||||
|
||||
---
|
||||
|
||||
### `export` — Portable database + schema archive
|
||||
|
||||
```bash
|
||||
# Write {db_name}-{timestamp}.tar.gz into {db_dir}/.exports
|
||||
bunx bun-sqlite export
|
||||
|
||||
# Explicit path / format
|
||||
bunx bun-sqlite export -o ./my-app.tar.gz
|
||||
bunx bun-sqlite export -f zip
|
||||
```
|
||||
|
||||
The archive holds `database.sqlite` (a consistent `VACUUM INTO` snapshot) and your schema file as `schema.<ext>`. Archives in `.exports` are trimmed to `max_exports`. `.zip` needs the `zip` binary.
|
||||
|
||||
---
|
||||
|
||||
### `import` — Database file, SQL script, or export archive
|
||||
|
||||
```bash
|
||||
# Interactive picker (from {db_dir}/.exports)
|
||||
bunx bun-sqlite import
|
||||
|
||||
# Full export (database + schema)
|
||||
bunx bun-sqlite import ./my-app.tar.gz
|
||||
|
||||
# Archive: database only / schema only
|
||||
bunx bun-sqlite import ./my-app.tar.gz --sql-only
|
||||
bunx bun-sqlite import ./my-app.tar.gz --schema-only
|
||||
|
||||
# A SQLite database file, or an SQL script (run into a fresh database)
|
||||
bunx bun-sqlite import ./other.db
|
||||
bunx bun-sqlite import ./dump.sql
|
||||
```
|
||||
|
||||
The current database is backed up to `db_backup_dir` before it is replaced. A `.ts`/`.js` schema from an archive runs as code on the next load, so `import` asks before writing it (pass `--yes` to skip the prompt).
|
||||
|
||||
---
|
||||
|
||||
## CRUD API
|
||||
|
||||
Import the default export:
|
||||
@@ -757,12 +797,16 @@ bun-sqlite/
|
||||
│ │ ├── schema.ts # `schema` command
|
||||
│ │ ├── typedef.ts # `typedef` command
|
||||
│ │ ├── backup.ts # `backup` command
|
||||
│ │ └── restore.ts # `restore` command
|
||||
│ │ ├── restore.ts # `restore` command
|
||||
│ │ ├── export.ts # `export` command
|
||||
│ │ └── import.ts # `import` command
|
||||
│ ├── functions/
|
||||
│ │ └── init.ts # Config + schema loader
|
||||
│ │ ├── init.ts # Loads config, schema and client into globals
|
||||
│ │ └── grab-sqlite-client.ts # Database client (bun:sqlite + sqlite-vec)
|
||||
│ ├── lib/
|
||||
│ │ ├── db-handler.ts # Runs every CRUD query
|
||||
│ │ └── schema/ # Schema synchronization (one step per file, + tests)
|
||||
│ ├── lib/sqlite/
|
||||
│ │ ├── index.ts # Database client (bun:sqlite + sqlite-vec)
|
||||
│ │ ├── db-schema-manager.ts # Schema synchronization engine
|
||||
│ │ ├── db-select.ts # Select implementation
|
||||
│ │ ├── db-insert.ts # Insert implementation
|
||||
│ │ ├── db-update.ts # Update implementation
|
||||
@@ -778,7 +822,9 @@ bun-sqlite/
|
||||
│ ├── sql-gen-operator-gen.ts # Equality operator mapper
|
||||
│ ├── sql-equality-parser.ts # Equality string parser
|
||||
│ ├── append-default-fields-to-db-schema.ts
|
||||
│ ├── grab-db-dir.ts # Resolve db/backup directory paths
|
||||
│ ├── resolve-and-load-data-file.ts # Load .ts/.js/.json/.yaml config and schema files
|
||||
│ ├── export-archive.ts # Read/write export archives
|
||||
│ ├── grab-db-dir.ts # Resolve db/backup/export directory paths
|
||||
│ ├── grab-db-backup-file-name.ts # Generate timestamped backup filename
|
||||
│ ├── grab-sorted-backups.ts # List backups sorted newest-first
|
||||
│ ├── grab-backup-data.ts # Parse metadata from a backup filename
|
||||
|
||||
Reference in New Issue
Block a user