{"id":21404317,"url":"https://github.com/boost/consyncful","last_synced_at":"2025-07-27T00:04:36.664Z","repository":{"id":34838919,"uuid":"171951937","full_name":"boost/consyncful","owner":"boost","description":"Contentful to local database synchronisation for Rails","archived":false,"fork":false,"pushed_at":"2025-05-27T02:12:37.000Z","size":118,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-24T00:55:51.561Z","etag":null,"topics":["ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/boost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2019-02-21T22:00:08.000Z","updated_at":"2025-05-27T02:12:10.000Z","dependencies_parsed_at":"2024-05-31T05:21:45.991Z","dependency_job_id":"17ef5ff8-5e70-43e3-b1bd-28199273201a","html_url":"https://github.com/boost/consyncful","commit_stats":{"total_commits":107,"total_committers":11,"mean_commits":9.727272727272727,"dds":0.6261682242990654,"last_synced_commit":"d1d714d2a73449e02bc3686924e55769d12a2bdf"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/boost/consyncful","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boost%2Fconsyncful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boost%2Fconsyncful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boost%2Fconsyncful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boost%2Fconsyncful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boost","download_url":"https://codeload.github.com/boost/consyncful/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boost%2Fconsyncful/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267272134,"owners_count":24062416,"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","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ruby-gem"],"created_at":"2024-11-22T16:14:25.570Z","updated_at":"2025-07-27T00:04:36.625Z","avatar_url":"https://github.com/boost.png","language":"Ruby","readme":"# Consyncful\n\nContentful -\u003e local database synchronisation for Rails\n\nRequesting complicated models from the Contentful Delivery API in Rails applications is often too slow, and makes testing applications painful. Consyncful uses Contentful's synchronisation API to keep a local, up-to-date copy of the entire content in a Mongo database.\n\nOnce the content is available locally, finding and interact with contentful data is as easy as using [Mongoid](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-documents/) ODM.\n\nThis gem doesn't provide any integration with the management API, or any way to update Contentful models from the local store. It is strictly read only.\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Creating contentful models in your Rails app](#creating-contentful-models-in-your-rails-app)\n  - [Synchronizing contentful data](#synchronizing-contentful-data)\n  - [Finding and interacting with models](#finding-and-interacting-with-models)\n    - [Querying](#querying)\n    - [References](#references)\n    - [Finding entries from different content types](#finding-entries-from-different-content-types)\n  - [Sync callbacks](#sync-callbacks)\n  - [Using Locales for specific fields](#using-locales-for-specific-fields)\n  - [Configuring what Mongo database Consyncful uses](#configuring-what-mongo-database-consyncful-uses)\n  - [Why do I have to use MongoDB?](#why-do-i-have-to-use-mongodb)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'consyncful'\n```\n\nAnd then execute:\n\n    $ bundle\n\nIf you don't already use Mongoid, generate a mongoid.yml by running:\n\n    $ rake g mongoid:config\n\nAdd an initializer:\n\nConsyncful uses [contentful.rb](https://github.com/contentful/contentful.rb); client options are as documented there. Sync options are documented in the [Content Delivery Sync API docs](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization).\n```rb\nConsyncful.configure do |config|\n  config.locale = 'en-NZ'\n  config.contentful_client_options = {\n    api_url: 'cdn.contentful.com',\n    space: 'space_id',\n    access_token: 'ACCESS TOKEN',\n    environment: 'master',        # optional\n    logger: Logger.new(STDOUT)    # optional for debugging\n  }\n\n  # optional to override the Sync API defaults\n  config.contentful_sync_options = { \n    limit: 50\n  }\nend\n```\n\n## Usage\n\n### Creating contentful models in your Rails app\n\nCreate models by inheriting from `Consyncful::Base`\n\n```ruby\nclass ModelName \u003c Consyncful::Base\n  contentful_model_name 'contentfulTypeName'\nend\n```\n\nModel fields will be dynamically assigned, but Mongoid dynamic fields are not accessible if the entry has an empty field. If you want the accessor methods to be reliably available for fields it is recommended to define the fields in the model:\n\n```ruby\nclass ModelName \u003c Consyncful::Base\n  contentful_model_name 'contentfulTypeName'\n\n  field :title\n  field :is_awesome, type: Boolean\nend\n```\n\nContentful reference fields are a bit special compared with standard Mongoid associations. Consyncful provides the following helpers to set up the correct relationships:\n\n```ruby\nclass ModelWithReferences \u003c Consyncful::Base\n  contentful_model_name 'contentfulTypeName'\n\n  references_one :thing\n  references_many :other_things\nend\n```\n\n### Synchronizing contentful data\n\nTo run a synchronization process run:\n\n    $ rake consyncful:sync\n\nThe first time you run this it will download all the Contentful content. It will then check every 15 seconds for changes to the content and update/delete records in the database when changes are made in Contentful.\n\nIf you want to synchronise from scratch, run:\n\n    $ rake consyncful:refresh\n\nIt is recommended to refresh your data if you change model names.\n\nNow you've synced your data, it is all available via your Rails models.\n\n### Finding and interacting with models\n\n#### Querying\nModels are available using standard Mongoid [queries](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-queries/).\n\n```ruby\ninstance = ModelName.find_by(instance: 'foo')\n\ninstance.is_awesome # true\n```\n\n#### References\nReferences work like you would expect:\n\n```ruby\n\ninstance = ModelWithReferences.find('contentfulID')\n\ninstance.thing # returns the referenced thing\ninstance.other_things # all the referenced things, polymorphic, so might be different types\n```\n\n**Except**:\n`references_many` associations return objects in a different order from how they are ordered in Contentful. If you want them in the order they appear in Contentful, use the `.in_order` helper:\n\n```ruby\ninstance.other_things.in_order # ordered the same as in Contentful\n```\n\n#### Finding entries from different content types\n\nBecause all Contentful models are stored as polymorphic subtypes of `Consyncful::Base`, you can query all entries without knowing what type you are looking for:\n\n```ruby\nConsyncful::Base.where(title: 'a title') # [ #\u003cModelName\u003e, #\u003cOtherModelName\u003e ]\n```\n\n### Sync callbacks\n\nYou may want to attach some application logic to happen before or after a sync run, for example to update caches.\n\nCallbacks can be registered using:\n\n```ruby\nConsyncful::Sync.before_run do\n  # do something before the run\nend\n```\n\n```ruby\nConsyncful::Sync.after_run do |updated_ids|\n  # invalidate cache for updated_ids, or something\nend\n```\n\n### Using Locales for specific fields\n\nIf fields have multiple locales then the default locale will be mapped to the field name. Additional locales will have a suffix (lower snake case) on the field name. e.g title (default), title_mi_nz (New Zealand Maori mi-NZ)\n\n### Preserving Contentful timestamps\n\nIf you need to access the timestamps from Contentful, you can enable it by setting `preserve_contentful_timestamps` to `true`.\n\n```rb\nConsyncful.configure do |config|\n  # Consyncful models will have two extra fields that contains the value of timestamps in Contentful.\n  # contentful_created_at\n  # contentful_updated_at\n  config.preserve_contentful_timestamps = true # defaults to false\nend\n```\n\n### Sync specific contents using [Contentful Tag](https://www.contentful.com/help/tags/).\nYou can configure Consyncful to sync or ignore specific contents using Contentful Tag.\n\n```rb\nConsyncful.configure do |config|\n  # Any contents tagged with 'myTag' will be stored in the database. \n  # Other contents without 'myTag' would be ignored.\n  config.content_tags = ['myTag'] # defaults to []\nend\n```\n\nAlso, you can ignore contents with specific Tags.\n\n```rb\nConsyncful.configure do |config|\n  # Any contents tagged with 'ignoreTag' won't be stored in the database.\n  config.ignore_content_tags = ['ignoreTag'] # defaults to []\nend\n```\n\n### Configuring what Mongo database Consyncful uses\n\nYou can also configure what Mongoid client Consyncful uses and the name of the collection the entries are stored under. This is useful if you want to have your consyncful data hosted in a different mongo database than your application-specific mongo database.\n\n```rb\nConsyncful.configure do |config|\n  config.mongo_client = :consyncful # defaults to :default (referencing the clients in mongoid.yml)\n  config.mongo_collection = 'contentful_models' # this is the default\nend\n```\n\n### Why do I have to use MongoDB?\n\nConsyncful currently only supports Mongoid ODM because models have dynamic schemas. And that's all we've had a chance to work out so far. The same pattern might be able to be extended to work with ActiveRecord, but having to migrate the local database as well as your contentful content type's seems tedious.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/boost/consyncful.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboost%2Fconsyncful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboost%2Fconsyncful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboost%2Fconsyncful/lists"}