{"id":28089468,"url":"https://github.com/bingcoke/pouchdb-adapter-sqlite","last_synced_at":"2025-05-13T12:58:34.804Z","repository":{"id":286249195,"uuid":"960857266","full_name":"BingCoke/pouchdb-adapter-sqlite","owner":"BingCoke","description":"The PouchDB adapter uses SQLite as its underlying database engine. Theoretically, it is compatible with any database that provides standard SQL language interfaces.","archived":false,"fork":false,"pushed_at":"2025-04-23T05:02:25.000Z","size":796,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-23T06:19:44.079Z","etag":null,"topics":["capacitor","cordova","database","pouchdb","react-native","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BingCoke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-05T07:58:32.000Z","updated_at":"2025-04-23T05:02:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"c53bc47d-1b8e-4462-8dca-c5ec609b2bcb","html_url":"https://github.com/BingCoke/pouchdb-adapter-sqlite","commit_stats":null,"previous_names":["bingcoke/pouchdb-adapter-sqlite"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BingCoke%2Fpouchdb-adapter-sqlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BingCoke%2Fpouchdb-adapter-sqlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BingCoke%2Fpouchdb-adapter-sqlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BingCoke%2Fpouchdb-adapter-sqlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BingCoke","download_url":"https://codeload.github.com/BingCoke/pouchdb-adapter-sqlite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948387,"owners_count":21988953,"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":["capacitor","cordova","database","pouchdb","react-native","sqlite3"],"created_at":"2025-05-13T12:58:33.979Z","updated_at":"2025-05-13T12:58:34.794Z","avatar_url":"https://github.com/BingCoke.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PouchDB SQLite Adapter\n\n\u003e **Project Status**: This project is currently under active development. While we strive to ensure compatibility across various SQLite implementations (especially for binary data storage), there may still be edge cases. We welcome any issues, suggestions or discussions to help improve the adapter.\n\nThis package provides a core implementation of a generic PouchDB SQLite adapter that works with any SQLite database supporting basic SQL operations.\n\n## Design Philosophy\n\nThe core design philosophy of this adapter is to support different SQLite implementations through abstraction and interface separation. The adapter's core functionality is decoupled from specific SQLite implementations, enabling the same codebase to work across various platforms and environments.\n\n## Architecture\n\nThe adapter follows a layered architecture:\n\n1. **Core Layer**: Implements all PouchDB adapter functionalities including document storage, querying, and attachment handling\n2. **Abstract Database Interface Layer**: Defines interfaces for SQLite database interactions\n3. **Implementation Layer**: Provides concrete implementations for different SQLite libraries\n\n## Supported SQLite Implementations\n\nCurrently supported or planned SQLite implementations:\n\n- [x] [Capacitor SQLite (@capacitor-community/sqlite)](https://github.com/capacitor-community/sqlite)\n- [x] [Expo-Sqlite](https://github.com/expo/expo/tree/sdk-52/packages/expo-sqlite)\n- [x] [OP SQLite (@op-engineering/op-sqlite)](https://github.com/OP-Engineering/op-sqlite)\n- [ ] Other SQLite implementations conforming to the interface specification\n\n## Upcoming Features\n\n- [x]  **More Efficient Attachment Handling**\n   Currently, the adapter uses pouchdb's official adapter-util to first convert data to binary string format. However, some SQLite implementations require converting this binary string to Uint8Array for storage. This creates unnecessary overhead when the input data is already in Uint8Array format. We plan to optimize this conversion pipeline to improve performance.\n\n- [ ] **Extended SQLite Support**\n   We welcome community contributions through issues and pull requests to add support for additional SQLite implementations. Our roadmap includes expanding compatibility with more SQLite variants.\n\n## Usage\nInstall Core First:\n\n```shell\n# install pouchdb\nyarn add pouchdb-core pouchdb-replication pouchdb-adapter-http\n# install sqlite adapter\nyarn add pouchdb-adapter-sqlite-core\n# install specific sqlite implementation\nyarn add pouchdb-adapter-expo-sqlite\n```\n\nThen Install the SQLite Implementation Plugin:\n\n```shell\n# install expo-sqlite plugin\nyarn add pouchdb-adapter-expo-sqlite\n# install capacitor-sqlite plugin\nyarn add pouchdb-adapter-capacitor-sqlite\n# install op-sqlite plugin\nyarn add pouchdb-adapter-op-sqlite\n```\n\n\nWhen creating a PouchDB instance, specify the `adapter` name as `sqlite` and configure the `sqliteImplementation` setting. Make sure to first inject the sqlite-core plugin, followed by the specific SQLite implementation plugin.\n\n```typescript\nimport PouchDB from \"pouchdb-core\";\nimport HttpPouch from \"pouchdb-adapter-http\";\nimport replication from \"pouchdb-replication\";\nimport OPSQLitePlugin from \"pouchdb-adapter-opsqlite\";\nimport SqlitePlugin from \"pouchdb-adapter-sqlite-core\";\n\nconst DB = PouchDB.plugin(HttpPouch)\n  .plugin(replication)\n  .plugin(SqlitePlugin)\n  .plugin(OPSQLitePlugin);\n\n\nconst db = new DB('example', {\n  adapter:'sqlite',\n  sqliteImplementation: 'expo-sqlite',\n});\n\nexport const remoteDB = new Db(\"http://192.168.0.104:8080/couchdb/example\", {\n  auth: { username: \"admin\", password: \"123456\" },\n  adapter: \"http\",\n});\n\nexport const sync = PouchDB.sync(db, remoteDB, { live: true, retry: true });\n```\n\n## NOTE!!! If you use React Native\nPlease check out the end of Readme to see how to resolve issues with React Native and Pouchdb.\n\u003e ***This is not an issue with our library, but rather a compatibility problem between React Native and PouchDB. As you know, React Native operates in its own environment with its own polyfills, and these polyfills do not fully support standard interface definitions sometimes. To resolve these issues, custom adaptations are necessary.***\n\n## More Examples\nSee the example directory for additional usage examples. Database-related code can be found in the db subdirectory.\n\n## Extending Support\nTo add support for other SQLite implementations, simply create an adapter that implements the abstract database interface.\n\n## Attachment Storage and Retrieval Configuration\nThis release includes optimizations for binary data processing across different SQLite databases. If you need to:\n\nAdapt your SQLite implementation\n\nResolve binary storage issues with specific SQLite versions\n\nConfigure attachment-related settings\n\nPlease refer to this documentation for detailed guidance.[about attachment](./docs/attachment.md)\n\n## Known Issues and Workarounds\n\n### React Native with PouchDB 9.0.0\nWhen using this adapter with PouchDB 9.0.0 in React Native, you may encounter errors related to `pouchdb-errors`.\nTo fix it you just need to patch pouchdb-errors library with this version: https://github.com/pouchdb/pouchdb/blob/master/packages/node_modules/pouchdb-errors/src/index.js\nYou can use patch-package for this. https://www.npmjs.com/package/patch-package\n\n### React Native Pollyfills\nIf you are using React Native, you may need to include the following pollyfills: `react-native-quick-crypto`, `readable-stream`, `@craftzdog/react-native-buffer`\n```shell\nyarn add reac-native-quick-crypto readable-stream @craftzdog/react-native-buffer\n```\n\nYou need to install babel-plugin-module-resolver, it's a babel plugin that will alias any imports in the code with the values you pass to it. It tricks any module that will try to import certain dependencies with the native versions we require for React Native.\n\n```shell\nyarn add --dev babel-plugin-module-resolver\n```\n\nThen, in your babel.config.js, add the plugin to swap the crypto, stream and buffer dependencies:\n\n```js\nmodule.exports = {\n  ...\n  plugins: [\n    [\n      'module-resolver',\n      {\n        alias: {\n          'crypto': 'react-native-quick-crypto',\n          'stream': 'readable-stream',\n          'buffer': '@craftzdog/react-native-buffer',\n        },\n      },\n   ],\n    ...\n  ],\n};\n```\n\n### Peer Dependencies\nIf you are using React Native, you may need to add the following peer dependencies:\n\n```shell\nyarn add react-native-blob-jsi-helper react-native-quick-base64\n```\n\n***Additionally, please review the post-resolution validation details provided by the package manager during dependency installation, as well as the README documentation of the corresponding SQLite implementation library.***\n\n## Acknowledgments\nSpecial thanks to @craftzdog for the open-source project: [pouchdb-adapter-react-native-sqlite](https://github.com/craftzdog/pouchdb-adapter-react-native-sqlite). This project is built upon their implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbingcoke%2Fpouchdb-adapter-sqlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbingcoke%2Fpouchdb-adapter-sqlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbingcoke%2Fpouchdb-adapter-sqlite/lists"}