{"id":29395201,"url":"https://github.com/medz/refine-sqlx","last_synced_at":"2026-04-14T04:31:52.383Z","repository":{"id":303881828,"uuid":"1017008444","full_name":"medz/refine-sqlx","owner":"medz","description":"A powerful, cross-platform SQL data provider for Refine","archived":false,"fork":false,"pushed_at":"2025-07-10T04:57:27.000Z","size":967,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T08:43:40.338Z","etag":null,"topics":["bun","cloudflare-d1","data-provider","node","refine","sql","sqlite"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/refine-sqlx","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/medz.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2025-07-09T22:05:36.000Z","updated_at":"2025-07-10T04:58:01.000Z","dependencies_parsed_at":"2025-07-10T08:43:42.297Z","dependency_job_id":"952e5100-f58d-4d2a-9c7a-de1a28f37013","html_url":"https://github.com/medz/refine-sqlx","commit_stats":null,"previous_names":["medz/refine-sqlx"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/medz/refine-sqlx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medz%2Frefine-sqlx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medz%2Frefine-sqlx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medz%2Frefine-sqlx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medz%2Frefine-sqlx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/medz","download_url":"https://codeload.github.com/medz/refine-sqlx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medz%2Frefine-sqlx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264572188,"owners_count":23630199,"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":["bun","cloudflare-d1","data-provider","node","refine","sql","sqlite"],"created_at":"2025-07-10T11:27:11.636Z","updated_at":"2025-07-10T11:27:12.463Z","avatar_url":"https://github.com/medz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Refine SQL X\n\nA powerful, cross-platform SQL data provider for [Refine](https://refine.dev) with automatic SQLite adapter detection and support for multiple runtime environments.\n\n[![npm version](https://img.shields.io/npm/v/refine-sqlx.svg)](https://www.npmjs.com/package/refine-sqlx)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\n## ✨ Features\n\n- 🔄 **Universal SQLite Support** - Works with Bun, Node.js, Cloudflare Workers, and better-sqlite3\n- 🎯 **Automatic Runtime Detection** - Intelligently selects the best SQLite driver for your environment\n- 🏭 **Factory Pattern** - Lazy connection initialization for optimal performance\n- 💾 **Memory \u0026 File Databases** - Support for both `:memory:` and file-based SQLite databases\n- 🔐 **Transaction Support** - Built-in transaction handling where supported\n- 📦 **Batch Operations** - Efficient bulk operations with createMany, updateMany, deleteMany\n- 🎛️ **Full CRUD** - Complete Create, Read, Update, Delete operations\n- 🔍 **Advanced Filtering** - Rich filtering, sorting, and pagination capabilities\n- 🛡️ **Type Safe** - Full TypeScript support with comprehensive type definitions\n\n## 📦 Installation\n\n```bash\n# Using Bun\nbun add refine-sqlx\n\n# Using npm\nnpm install refine-sqlx\n\n# Using pnpm\npnpm add refine-sqlx\n\n# Using yarn\nyarn add refine-sqlx\n```\n\n## 🚀 Quick Start\n\n### Basic Usage\n\n```typescript\nimport { Refine } from '@refinedev/core';\nimport { createRefineSQL } from 'refine-sqlx';\n\n// Use in-memory SQLite database\nconst dataProvider = createRefineSQL(':memory:');\n\nconst App = () =\u003e (\n  \u003cRefine dataProvider={dataProvider}\u003e\n    {/* Your app components */}\n  \u003c/Refine\u003e\n);\n```\n\n### File-based Database\n\n```typescript\nimport { createRefineSQL } from 'refine-sqlx';\n\n// Use a file-based SQLite database\nconst dataProvider = createRefineSQL('./database.sqlite');\n```\n\n## 🏗️ Platform-Specific Usage\n\n### Bun Runtime\n\n```typescript\nimport { Database } from 'bun:sqlite';\nimport { createRefineSQL } from 'refine-sqlx';\n\nconst db = new Database(':memory:');\nconst dataProvider = createRefineSQL(db);\n```\n\n### Node.js (v24+)\n\n```typescript\nimport { DatabaseSync } from 'node:sqlite';\nimport { createRefineSQL } from 'refine-sqlx';\n\nconst db = new DatabaseSync(':memory:');\nconst dataProvider = createRefineSQL(db);\n```\n\n### Cloudflare D1\n\n```typescript\nimport { createRefineSQL } from 'refine-sqlx';\n\nexport default {\n  async fetch(request: Request, env: Env): Promise\u003cResponse\u003e {\n    const dataProvider = createRefineSQL(env.DB); // D1 database binding\n    // Your worker logic here\n  },\n};\n```\n\n### Better SQLite3 (Fallback)\n\n```typescript\nimport Database from 'better-sqlite3';\nimport { createRefineSQL } from 'refine-sqlx';\n\nconst db = new Database(':memory:');\nconst dataProvider = createRefineSQL(db);\n```\n\n## 🔧 Advanced Configuration\n\n### Lazy Connection with Factory Pattern\n\n```typescript\nimport { createRefineSQL } from 'refine-sqlx';\n\nconst dataProvider = createRefineSQL({\n  async connect() {\n    // Returns your client.\n  }\n});\n```\n\n### Custom SQL Client\n\n```typescript\nimport { createRefineSQL } from 'refine-sqlx';\nimport type { SqlClient } from 'refine-sqlx';\n\nconst customClient: SqlClient = {\n  async query(query) {\n    // Your custom query implementation\n    return { columnNames: [], rows: [] };\n  },\n\n  async execute(query) {\n    // Your custom execute implementation\n    return { changes: 0, lastInsertId: undefined };\n  },\n\n  // Optional\n  async transaction(fn) {\n    // Your custom transaction implementation\n    return await fn(this);\n  }\n};\n\nconst dataProvider = createRefineSQL(customClient);\n// OR\n// createRefineSQL({ connect: () =\u003e customClient })\n```\n\n## 📊 Usage Examples\n\n### Complete CRUD Operations\n\n```typescript\nimport { createRefineSQL } from 'refine-sqlx';\n\nconst dataProvider = createRefineSQL(':memory:');\n\n// Create a record\nconst createResult = await dataProvider.create({\n  resource: 'users',\n  variables: {\n    name: 'John Doe',\n    email: 'john@example.com',\n    age: 30\n  }\n});\n\n// Get a list with filtering and pagination\nconst listResult = await dataProvider.getList({\n  resource: 'users',\n  pagination: { current: 1, pageSize: 10 },\n  filters: [\n    { field: 'age', operator: 'gte', value: 18 }\n  ],\n  sorters: [\n    { field: 'name', order: 'asc' }\n  ]\n});\n\n// Update a record\nconst updateResult = await dataProvider.update({\n  resource: 'users',\n  id: 1,\n  variables: { age: 31 }\n});\n\n// Delete a record\nconst deleteResult = await dataProvider.deleteOne({\n  resource: 'users',\n  id: 1\n});\n```\n\n### Batch Operations\n\n```typescript\n// Create multiple records\nconst createManyResult = await dataProvider.createMany({\n  resource: 'users',\n  variables: [\n    { name: 'Alice', email: 'alice@example.com', age: 25 },\n    { name: 'Bob', email: 'bob@example.com', age: 30 },\n    { name: 'Charlie', email: 'charlie@example.com', age: 35 }\n  ]\n});\n\n// Update multiple records\nconst updateManyResult = await dataProvider.updateMany({\n  resource: 'users',\n  ids: [1, 2, 3],\n  variables: { status: 'active' }\n});\n\n// Delete multiple records\nconst deleteManyResult = await dataProvider.deleteMany({\n  resource: 'users',\n  ids: [1, 2, 3]\n});\n```\n\n## 🔍 Filtering \u0026 Sorting\n\nRefine SQL X supports all standard Refine filtering operators:\n\n```typescript\nconst result = await dataProvider.getList({\n  resource: 'users',\n  filters: [\n    { field: 'name', operator: 'contains', value: 'John' },\n    { field: 'age', operator: 'gte', value: 18 },\n    { field: 'age', operator: 'lte', value: 65 },\n    { field: 'email', operator: 'ne', value: null },\n    { field: 'status', operator: 'in', value: ['active', 'pending'] }\n  ],\n  sorters: [\n    { field: 'created_at', order: 'desc' },\n    { field: 'name', order: 'asc' }\n  ]\n});\n```\n\n### Supported Filter Operators\n\n- `eq` - Equal\n- `ne` - Not equal\n- `lt` - Less than\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `gte` - Greater than or equal\n- `in` - In array\n- `nin` - Not in array\n- `contains` - Contains (LIKE %value%)\n- `ncontains` - Not contains\n- `containss` - Contains case sensitive\n- `ncontainss` - Not contains case sensitive\n- `between` - Between two values\n- `nbetween` - Not between two values\n- `null` - Is null\n- `nnull` - Is not null\n\n## 🏗️ Architecture\n\n### Runtime Detection\n\nRefine SQL X automatically detects your runtime environment and selects the optimal SQLite driver:\n\n1. **Cloudflare Workers** - Uses D1 database bindings\n2. **Bun** - Uses `bun:sqlite` (native)\n3. **Node.js ≥24** - Uses `node:sqlite` (native)\n4. **Fallback** - Uses `better-sqlite3` package\n\n### Transaction Support\n\nTransactions are automatically handled where supported:\n\n```typescript\n// Transactions are used internally for batch operations\nconst result = await dataProvider.createMany({\n  resource: 'users',\n  variables: [...] // All records created in a single transaction\n});\n```\n\n\u003e [!TIP]\n\u003e D1 not supported transaction, fallback using `batch`.\n\n## 🧪 Testing\n\n```bash\n# Run unit tests\nbun test\n\n# Run integration tests for all platforms\nbun run test:integration-bun\nbun run test:integration-node\nbun run test:integration-better-sqlite3\n\n# Build the library\nbun run build\n\n# Format code\nbun run format\n```\n\n## 📋 Requirements\n\n- **Peer Dependencies**: `@refinedev/core ^4`\n- **Optional Dependencies**: `better-sqlite3 ^12` (for fallback support)\n- **Runtime SQLite Support**:\n  - Bun 1.0+ (for `bun:sqlite`)\n  - Node.js 24+ (for `node:sqlite`)\n  - Node.js 20+ (with `better-sqlite3`)\n  - Cloudflare Workers (with D1 bindings)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [Refine Documentation](https://refine.dev/docs)\n- [GitHub Repository](https://github.com/medz/refine-sqlx)\n- [npm Package](https://www.npmjs.com/package/refine-sqlx)\n\n---\n\nMade with ❤️ for Seven\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedz%2Frefine-sqlx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedz%2Frefine-sqlx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedz%2Frefine-sqlx/lists"}