{"id":20434248,"url":"https://github.com/alex8088/sqlite3-queries","last_synced_at":"2025-04-12T21:11:46.806Z","repository":{"id":230552833,"uuid":"779624949","full_name":"alex8088/sqlite3-queries","owner":"alex8088","description":"A type-safe and promise-based query client for node sqlite3.","archived":false,"fork":false,"pushed_at":"2024-04-11T15:44:47.000Z","size":120,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T15:21:21.098Z","etag":null,"topics":["node-sqlite3","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alex8088.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-30T10:43:50.000Z","updated_at":"2025-02-25T18:44:10.000Z","dependencies_parsed_at":"2024-03-30T12:20:23.775Z","dependency_job_id":"cb9851e3-cb89-4da7-b353-73a450324169","html_url":"https://github.com/alex8088/sqlite3-queries","commit_stats":null,"previous_names":["alex8088/sqlite3-queries"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Fsqlite3-queries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Fsqlite3-queries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Fsqlite3-queries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Fsqlite3-queries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alex8088","download_url":"https://codeload.github.com/alex8088/sqlite3-queries/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631682,"owners_count":21136562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node-sqlite3","sqlite3"],"created_at":"2024-11-15T08:25:27.331Z","updated_at":"2025-04-12T21:11:46.775Z","avatar_url":"https://github.com/alex8088.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003esqlite3-queries\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eA type-safe and promise-based query client for node sqlite3\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/npm/v/sqlite3-queries?color=orange\u0026label=version\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/alex8088/sqlite3-queries?color=blue\" alt=\"license\" /\u003e\n\u003c/p\u003e\n\n## Features\n\n- SQL-based\n- Promise-based\n- Type-safe\n- Support automatic migration\n\n## Install\n\n```sh\nnpm i sqlite3 sqlite3-queries\n```\n\n## Usage\n\n#### Opening Database\n\n- Open an anonymous in-memory database\n\n```ts\nimport { Dbo } from 'sqlite3-queries'\n\nconst dbo = new Dbo()\nawait dbo.open()\n```\n\n- Open a physical disk database\n\n```ts\nimport path from 'node:path'\nimport { Dbo } from 'sqlite3-queries'\n\nconst dbo = new Dbo(path.join(__dirname, '/tmp/database.db'))\nawait dbo.open()\n```\n\n- Open a verbose database for debugging\n\n```ts\nimport { Dbo } from 'sqlite3-queries'\n\nconst dbo = new Dbo(':memory:', { verbose: true })\nawait dbo.open()\n```\n\n#### Closing Database\n\n```ts\nawait dbo.close()\n```\n\n#### Tracing and Logging\n\n```js\nimport { Dbo } from 'sqlite3-queries'\n\nconst dbo = new Dbo(Dbo.IN_MEMORY_PATH, {\n  trace: 'run',\n  log: (info): void =\u003e {\n    console.log(`[${info.level}] Database#${info.channel} ${info.error} (${info.sql})`)\n  }\n})\n\nawait dbo.open()\n```\n\n#### Automatic Migration\n\n```js\nimport path from 'node:path'\nimport { Dbo, DbContext, DbMigration } from 'sqlite3-queries'\n\nclass UserContext extends DbContext {\n  constructor(fileName: string) {\n    const dbo = new Dbo(fileName)\n    super(dbo, UserContext.migrations)\n  }\n\n  static migrations: DbMigration[] = [\n    {\n      version: 1,\n      sqls: [\n        'CREATE TABLE IF NOT EXISTS users (id STRING PRIMARY KEY, name STRING)'\n      ]\n    },\n    {\n      version: 2,\n      sqls: ['ALTER TABLE users ADD COLUMN gender INTEGER DEFAULT (1)']\n    }\n  ]\n}\n\nconst db = new UserContext(path.join(__dirname, 'test.db'))\n\nawait db.open()\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eType Signature\u003c/b\u003e\u003c/summary\u003e\n\n```ts\n/**\n * Database migration describes.\n */\ntype DbMigration = {\n  /**\n   * Migration version. The initial version must be greater than `0`. A new\n   * version is defined on each migration and is incremented on the previous version.\n   */\n  version: number\n  /**\n   * Migration SQLs. The sql will run sequentially, and DDL sql should\n   * be written before DML sql.\n   */\n  sqls: string[]\n}\n\n/**\n * Database context base class. It has implemented automatic migration.\n */\ndeclare class DbContext {\n  readonly dbo: Dbo\n  readonly migrations: DbMigration[]\n  /**\n   * Database context.\n   * @param dbo Database object.\n   * @param migrations Database migrations.\n   */\n  constructor(dbo: Dbo, migrations: DbMigration[])\n  protected migrate(): Promise\u003cvoid\u003e\n  /**\n   * Get the database user_version.\n   */\n  getVersion(): Promise\u003cnumber\u003e\n  /**\n   * Open the database and apply migrations automatically.\n   */\n  open(): Promise\u003cvoid\u003e\n  /**\n   * Close the database.\n   */\n  close(): Promise\u003cvoid\u003e\n}\n```\n\n\u003c/details\u003e\n\n## APIs\n\nPromise-based APIs for sqlite3.\n\n#### `Open`\n\nType: `(mode?: number) =\u003e Promise\u003cvoid\u003e`\n\nOpen the database. The `mode` is one or more of `Dbo.OPEN_READONLY`, `Dbo.OPEN_READWRITE`, `Dbo.OPEN_CREATE`, `Dbo.OPEN_FULLMUTEX`, `Dbo.OPEN_URI`, `Dbo.OPEN_SHAREDCACHE`, `Dbo.OPEN_PRIVATECACHE`. Default: `OPEN_READWRITE | OPEN_CREATE | OPEN_FULLMUTEX`.\n\n#### `Close`\n\nType: `() =\u003e Promise\u003cvoid\u003e`\n\nClose the database.\n\n#### `Run`\n\nType: `(sql: string, params?: SqlQueryParam | (string | number)[]) =\u003e Promise\u003cRunResult\u003e`\n\nRuns the SQL query with the specified parameters.\n\n- With array parameters:\n\n```ts\nconst sql = `INSERT INTO user (id, name) VALUES (?, ?)`\nconst result = await dbo.run(sql, [0, 'Alexandra Roman'])\n```\n\n- With named parameters:\n\n```ts\nconst sql = `UPDATE user SET name = $name WHERE id = $id`\nconst result = await dbo.run(sql, { $id: 0, $name: 'Evie Le' })\n```\n\n#### `Get`\n\nType: `\u003cT extends Record\u003cstring, any\u003e\u003e(sql: string, params?: SqlQueryParam | (string | number)[]) =\u003e Promise\u003cT | undefined\u003e`\n\nRuns the SQL query with the specified parameters and returns a subsequent result row. If data is not found, `undefined` is returned.\n\n```ts\nconst sql = `SELECT * FROM user WHERE id=?`\nconst result = await dbo.get\u003c{ id: number; name: string }\u003e(sql, [0])\n\n// Output: {id: 0, name: 'Evie Le'}\n```\n\n#### `All`\n\nType: `\u003cT extends Record\u003cstring, any\u003e\u003e(sql: string, params?: SqlQueryParam | (string | number)[]) =\u003e Promise\u003cT[]\u003e`\n\nRuns the SQL query with the specified parameters and returns all result rows afterwards.\n\n```ts\nconst sql = `SELECT * FROM user`\nconst result = await dbo.all\u003c{ id: number; name: string }\u003e(sql)\n\n// Output: [{id: 0, name: 'Evie Le'}]\n```\n\n#### `Exec`\n\nType: `(sql: string) =\u003e Promise\u003cvoid\u003e`\n\nRuns all SQL queries in the supplied string.\n\n#### `Prepare`\n\nType: `(sql: string, runCallback: (stmt: Statement) =\u003e void) =\u003e void`\n\nPrepares the SQL statement and run the callback with the statement object.\n\n#### `Transaction`\n\nType: `(transactions: () =\u003e void) =\u003e Promise\u003cvoid\u003e`\n\nStart a transaction explicitly. A transaction is the propagation of one or more changes to the database. For example, if you are creating, updating, or deleting a record from the table, then you are performing transaction on the table. It is important to control transactions to ensure data integrity and to handle database errors.\n\n```ts\nawait dbo.transaction(() =\u003e {\n  dbo.prepare('INSERT INTO user (id, name) VALUES ($id, $name)', (stmt) =\u003e {\n    ;[\n      { $id: 2, $name: 'Jordan' },\n      { $id: 3, $name: `Ameer` }\n    ].forEach((p) =\u003e stmt.run(p))\n  })\n})\n```\n\n#### `LoadExtension`\n\nType: `(fileName: string) =\u003e Promise\u003cvoid\u003e`\n\nLoads a compiled SQLite extension into the database connection object.\n\n#### `Vacuum`\n\nType: `() =\u003e Promise\u003cvoid\u003e`\n\nRebuild the database file, repacking it into a minimal amount of disk space.\n\n#### `Pragma`\n\nType: `\u003cT extends Record\u003cstring, any\u003e\u003e(flag: string, value?: string | number): Promise\u003cT | undefined\u003e`\n\nExecutes the PRAGMA command to modify the operation of the SQLite library or to query the library for internal (non-table) data.\n\n```js\n// query cache size\ndbo.pragma('cache_size')\n\n// change cache size\ndbo.pragma('cache_size', 1000 * 1024)\n```\n\n#### `Escape`\n\nType: `(str: string) =\u003e string`\n\nEscape the `/`, `%`, and `_` characters of query parameters.\n\n#### `toSqlQueryParam`\n\nType: `(param: Record\u003cstring, string | number\u003e) =\u003e SqlQueryParam`\n\nConvert object parameters to sql query parameters. All object keys will be prefixed with `$`.\n\n## Using Sqlite3 APIs\n\nYou can use all the original APIs of Sqlite3.\n\n```ts\nconst dbo = new Dbo()\n\nawait dbo.open()\n\nconst smt = dbo.db.prepare('INSERT INTO user (id, name) VALUES (?, ?)')\n\nsmt.run([0, 'Alexandra Roman'])\n\ndbo.db.all('SELECT * FROM user', function (err, result) {\n  // ...\n})\n```\n\n## License\n\n[MIT](./LICENSE) copyright © 2024-present alex wei\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex8088%2Fsqlite3-queries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex8088%2Fsqlite3-queries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex8088%2Fsqlite3-queries/lists"}