Bridgetown Active Record plugin

This plugin adds Active Record support to Bridgetown sites (v1.2 or higher). You can pull data from a database (currently PostgreSQL is officially supported) during a static build or during server requests (or both!) and use many of the features you know and love from Active Record in Rails—including migrations!

In addition, if you also like using the Sequel gem for your database access, this plugin can support instantiating Sequel with a shared DB connection via the sequel-activerecord_connection extension (see below).

Installation

IMPORTANT NOTE: there's currently a compatibilty issue between Rails 7 gems and Rack version 3. For now, please add gem "rack", "~> 2.2" to your Gemfile before you install this plugin.

It's recommended you run our automation script to set up your project to support Active Record and DB models:

$ bin/bridgetown apply https://github.com/bridgetownrb/bridgetown-activerecord

Or for a fully manual setup:

$ bundle add bridgetown-activerecord

then replicate the individual steps outlined in the automation script.

You will need to decide on your database adapter of choice. For a typical PostgreSQL configuration, add the pg gem.

$ bundle add pg

When deploying to production, the DATABASE_URL ENV var will need to be set with the appropriate connection string…many hosting services will do this for you automatically.

Usage

Let's create a simple Movie model to load and save our favorite movies. Add the file models/movie.rb:

class Movie < ApplicationRecord
  validates :title, presence: true, uniqueness: { case_insensitive: true }

  def uppercase_title
    title.upcase
  end
end

Then add a new migration for the Movie model.

$ bin/bridgetown db:new_migration name=create_movies

That will create a new migration file in db/migrate. Edit the file so it looks like this:

class CreateMovies < ActiveRecord::Migration[7.0]
  def change
    create_table :movies do |t|
      t.string :title, null: false
      t.string :director
      t.integer :year

      t.timestamps
    end
  end
end

Awesome, now let's create the database and run the migration!

$ bin/bridgetown db:create
$ bin/bridgetown db:migrate

If all goes well, the database should be created, the migration run, a new db/schema.rb saved, and schema annotations added to the top of models/movie.rb!

Let's try it out in the Bridgetown console.

$ bin/bridgetown console

> Movie.count
0
> Movie.create(title: "Free Guy", director: "Shawn Levy", year: "2021") 
> Movie.count
1
> Movie.last
#<Movie:0x0000000109e26378> {
          :id => 1,
       :title => "Free Guy",
    :director => "Shawn Levy",
        :year => 2021,
  :created_at => 2022-03-12 23:24:28.98137 UTC,
  :updated_at => 2022-03-12 23:24:28.98137 UTC
}

You're ready to roll to take full advantage of Active Record database models in your Bridgetown site!

Changing the Models Directory

If you'd prefer to set up your models folder elsewhere other than ./models, you can move the files to another path and then update your Rakefile to pass in that path. For example, you could use the more familiar app/models:

require "bridgetown-activerecord"
BridgetownActiveRecord.load_tasks(models_dir: "app/models")

(Don't forget to update your autoload path in config/initializers.rb accordingly.)

Using with Sequel

To set up Sequel using the same database connection as Active Record, follow these steps:

First, install the sequel-activerecord_connection gem:

bundle add sequel-activerecord_connection

Next, update your configuration in config/initializers.rb as follows:

init :"bridgetown-activerecord", sequel_support: :postgres # or mysql2 or sqlite3

Now you should be able to call DB to access the Sequel API anywhere in your Bridgetown or Roda code:

DB.tables # => [:ar_internal_metadata, :schema_migrations, etc.]

Testing

Run bundle exec rake test to run the test suite
Or run script/cibuild to validate with Rubocop and Minitest together.

Contributing

Fork it (https://github.com/bridgetownrb/bridgetown-activerecord/fork)
Clone the fork using git clone to your local development machine.
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request