{"id":16558171,"url":"https://github.com/simonschiller/prefiller","last_synced_at":"2025-07-09T03:04:24.065Z","repository":{"id":44764806,"uuid":"272260787","full_name":"simonschiller/prefiller","owner":"simonschiller","description":"Prefiller is a Gradle plugin that generates pre-filled Room databases at compile time.","archived":false,"fork":false,"pushed_at":"2023-12-01T07:38:24.000Z","size":272,"stargazers_count":52,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-01T05:41:16.349Z","etag":null,"topics":["android","gradle-plugin","room"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonschiller.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}},"created_at":"2020-06-14T18:30:42.000Z","updated_at":"2024-06-27T09:29:46.000Z","dependencies_parsed_at":"2024-10-28T10:19:52.508Z","dependency_job_id":"0d9f8766-0db8-43bf-a6e5-3a553abda559","html_url":"https://github.com/simonschiller/prefiller","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonschiller%2Fprefiller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonschiller%2Fprefiller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonschiller%2Fprefiller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonschiller%2Fprefiller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonschiller","download_url":"https://codeload.github.com/simonschiller/prefiller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244135893,"owners_count":20403797,"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":["android","gradle-plugin","room"],"created_at":"2024-10-11T20:09:47.772Z","updated_at":"2025-03-21T10:32:33.837Z","avatar_url":"https://github.com/simonschiller.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://img.shields.io/github/workflow/status/simonschiller/prefiller/CI)](https://github.com/simonschiller/prefiller/actions)\n[![GitHub Release](https://img.shields.io/github/v/release/simonschiller/prefiller)](https://github.com/simonschiller/prefiller/releases)\n[![License](https://img.shields.io/github/license/simonschiller/prefiller)](https://github.com/simonschiller/prefiller/blob/main/LICENSE)\n\n# Prefiller\n\nPrefiller is a Gradle plugin that generates pre-filled Room databases at compile time. \n\n## Motivation\n\nWith version 2.2, the Room persistence library added [support for pre-populated databases](https://medium.com/androiddevelopers/packing-the-room-pre-populate-your-database-with-this-one-method-333ae190e680). This works by including a pre-filled database in the Android app assets. Generating this database can be tedious and error-prone and has to be repeated whenever the underlying schema or data changes.\n\nPrefiller offers a convenient way to generate pre-filled databases at compile time. You simply provide a script file which populates your database, Prefiller takes care of the rest. It will generate a database matching the latest schema, execute your script on this database and include the database in the assets. This way, changing the schema or adding additional pre-filled data is much easier. Additionally, the changes to the pre-filled database are now present in script form, making changes easier to review in pull requests.\n\n## Usage\n\nTo start using Prefiller, you just have to follow these steps.\n\n#### Add Prefiller to your project\n\nFirst you need to add the Prefiller plugin to your project by adding this block of code to your `build.gradle`.\n\n```groovy\nplugins {\n    id \"io.github.simonschiller.prefiller\" version \"1.4.0\"\n}\n```\n\nAlternatively, you can also use the legacy plugin API. Simply add the following snippet to your top-level `build.gradle`.\n\n```groovy\nbuildscript {\n    repositories {\n        maven {\n            url \"https://plugins.gradle.org/m2/\"\n        }\n    }\n    dependencies {\n        classpath \"io.github.simonschiller:prefiller:1.4.0\"\n    }\n}\n```\n\nWhen you're using the legacy plugin API, you also have to apply the plugin in the `build.gradle` of your module.\n\n```groovy\napply plugin: \"io.github.simonschiller.prefiller\"\n```\n\nYou can also find instructions on how to use the Prefiller plugin on the [Gradle plugin portal](https://plugins.gradle.org/plugin/io.github.simonschiller.prefiller).\n\n#### Write your setup script\n\nNext you need to create a `.sql` script with all your setup statements. Simply place this file somewhere in your project. Prefiller will use this file to populate the database, so make sure the statements are valid and match the database schema. You can also supply multiple `.sql` files if you wish.\n\n```sql\n-- src/main/sql/setup.sql\n\nINSERT INTO people(firstname, lastname, age) VALUES (\"Mikael\", \"Burke\", 38);\nINSERT INTO people(firstname, lastname, age) VALUES (\"Ayana\", \"Clarke\", 12);\nINSERT INTO people(firstname, lastname, age) VALUES (\"Malachy\", \"Wall\", 24);\n```\n\n#### Configure the Prefiller plugin\n\nLastly, you have to configure the Prefiller plugin in your `build.gradle` by linking the database class with the script file you just created.\n\n```groovy\nprefiller {\n    database(\"people\") {\n        classname.set(\"com.example.PeopleDatabase\")\n        scripts.from(file(\"src/main/sql/setup.sql\"))\n    }\n}\n```\n\n#### Using the pre-filled database in code\n\nNow you're ready to go. Simply use the generated database file when you build your Room database.\n\n```kotlin\nval database = Room.databaseBuilder(context, com.example.PeopleDatabase::class.java, \"people.db\")\n    .createFromAsset(\"people.db\") // File name is configured in the plugin\n    .build()\n```\n\n## How it works\n\nRoom can be set up to generate a schema definition file, this file contains all information needed to construct a matching database. Prefiller simply parses this file, generates the database accordingly and runs the provided script file. To make this work, you have to make sure that Room is configured to generate schema files.\n\n```groovy\nandroid {\n    defaultConfig {\n        // Java\n        javaCompileOptions {\n            annotationProcessorOptions {\n                arguments[\"room.schemaLocation\"] = \"$projectDir/schemas\".toString()\n            }\n        }\n\n        // Kotlin KAPT\n        kapt {\n            arguments {\n                arg(\"room.schemaLocation\", \"$projectDir/schemas\")\n            }\n        }\n\n        // Kotlin KSP\n        ksp {\n            arg(\"room.schemaLocation\", \"$projectDir/schemas\")\n        }\n    }\n}\n```\n\nYou can find more information on how to do this in the [official Room documentation](https://developer.android.com/training/data-storage/room/migrating-db-versions#export-schema).\n\n## Working with this project\n\nThe source code of the plugin is located in the `prefiller` folder. The `sample` folder contains several sample projects that show how the plugin is used. The tests of these sample projects also function as E2E tests for the Prefiller plugin.\n\n* Build the plugin: `./gradlew :prefiller:assemble`\n* Run unit tests: `./gradlew :prefiller:test`\n    * By default, all tests will be executed against all compatible Gradle and Android Gradle plugin versions. If you want to run tests against a specific version, you can set the `GRADLE_VERSION` and `AGP_VERSION` environment variables.\n    * For example: `GRADLE_VERSION=7.5.1 AGP_VERSION=7.2.2 ./gradlew :prefiller:test`\n* Run all tests:\n    * First publish the plugin to your local Maven repo: `./gradlew :prefiller:publishToMavenLocal`\n    * Then execute the tests: `./gradlew test`\n\n## License\n\n```\nCopyright 2020 Simon Schiller\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonschiller%2Fprefiller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonschiller%2Fprefiller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonschiller%2Fprefiller/lists"}