Taylor Barnett | May 24, 2022

If you deploy your applications in regions around the globe and need to keep database read latency low, you will want to physically have a database nearby. With PlanetScale Portals, you can now create read-only regions to support your globally distributed applications and better serve your users worldwide.

Put your data where your users and applications are

Portals allow you to read data from regions closest to where you globally deploy your applications. Whether your application is deployed near Northern Virginia, Frankfurt, São Paulo, or any of our other PlanetScale regions, Portals can now provide lower read latency for your applications!

Today, each database in PlanetScale reads and writes from a single region. But with Portals, you can add as many distributed read-only regions as you want.

Without PlanetScale, it can be a hassle to set up a globally deployed database on your own. You might have to do capacity planning, deal with complicated pricing structures, and worry about your replication strategy or performance. Instead, with a couple of clicks, allow PlanetScale to operate your additional read-only regions for you.

An example of the power of Portals

To make this more concrete, let’s look at the read latency between different regions:

For an application deployed to Frankfurt, talking to a Northern Virginia database can add nearly an extra ~90ms PER query. By adding a read-only region in Frankfurt, we can reduce that to ~3ms per query. (Data based on select * from books limit 10.)

Connecting to your new read-only regions

You connect to your new read-only regions with a connection string, just like connecting to any other PlanetScale database branch or other MySQL databases. This connection string is specific to both your read-only region and production branch.

Let’s break down how this might look like in a Ruby on Rails application deployed in both São Paolo and Frankfurt.

Code example

In a Rails application, you can set up a connection to your read-only region.

First, modify your database.yml to include both a primary and read-only region connection.

default: &default
  adapter: trilogy
  encoding: utf8mb4
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  username: root
  password:
  socket: /tmp/mysql.sock

development:
  primary:
    <<: *default
    database: multi_region_rails_development
  primary_replica:
    <<: *default
    database: multi_region_rails_development
    replica: true

test:
  primary:
    <<: *default
    database: multi_region_rails_test
  primary_replica:
    <<: *default
    database: multi_region_rails_test
    replica: true

This will allow you to send queries to your read-only region or take advantage of Rails "automatic role switching" to route queries for you.

ActiveRecord::Base.connected_to(role: :reading) do
  books = Book.where(author: "Taylor")
  # all code in this block will be connected to the read-only region
end

You can set up your production application to connect to your nearest PlanetScale region for reads. This will result in your app having low-latency reads.

In this example, we have our connection details stored in Rails credentials.

<%
  # Our application has a region environment variable.
  # We check this variable and connect to the closest DB region.
  region = ENV["APP_REGION"]

  # When in Frankfurt, we use our Frankfurt region.
  # When in São Paolo, => São Paolo region.
  region_replica_mapping = {
      "fra" => Rails.application.credentials.planetscale_fra,
      "gra" => Rails.application.credentials.planetscale_gra
  }

  # If no specific region exists, we’ll connect to the primary.
  db_replica_creds = region_replica_mapping[region] || Rails.application.credentials.planetscale
%>

production:
  primary:
    <<: *default
    username: <%= Rails.application.credentials.planetscale&.fetch(:username) %>
    password: <%= Rails.application.credentials.planetscale&.fetch(:password) %>
    database: <%= Rails.application.credentials.planetscale&.fetch(:database) %>
    host: <%= Rails.application.credentials.planetscale&.fetch(:host) %>
    ssl_mode: verify_identity
  primary_replica:
    <<: *default
    username: <%= db_replica_creds.fetch(:username) %>
    password: <%= db_replica_creds.fetch(:password) %>
    database: <%= db_replica_creds.fetch(:database) %>
    host: <%= db_replica_creds.fetch(:host) %>
    ssl_mode: <%= Trilogy::SSL_VERIFY_IDENTITY %>
    replica: true

Once this is in place, we can now have our globally deployed app read data from our globally deployed database. This will result in much faster GET requests for anyone in that region. Any writes will still go to the primary.

Automatic role switching and reading your own writes

We can take this one step further by having all our read queries hit the read-only region without specifying it in our code. We can also tell Rails to read from our primary if the user recently wrote to the database. This protects our users from ever reading stale data due to replication lag.

To do this, we need to set reading/writing roles for our models:

# app/models/application_record.rb
class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class

  connects_to database: { writing: :primary, reading: :primary_replica }
end

Then we can enable automatic role switching by adding the following to our production config.

# config/environments/production.rb
config.active_record.database_selector = { delay: 2.seconds }
config.active_record.database_resolver = ActiveRecord::Middleware::DatabaseSelector::Resolver
config.active_record.database_resolver_context = ActiveRecord::Middleware::DatabaseSelector::Resolver::Session

This tells Rails to send all reads to our read-only region and writes to our primary. After each write, it will set a cookie that will send all reads to the primary for 2 seconds, allowing users to read their own writes.

(Also, thank you to PlanetScale software engineer, Mike Coutermarsh, for help with the Ruby on Rails code in this section.)

Pricing

Any database on a Base or Enterprise plan can create read-only database regions. The pricing for Portals is based on storage costs and row reads.

Storage costs

Your storage costs will increase linearly with the number of read-only regions you purchase. For example, if your production branch is 10GB, each read-only region added will increase your total storage cost by 10GB. Portals’ storage costs are prorated by month. If you added a read-only region to your 10GB branch on the 15th, you’ll get billed for 5GB of usage.

Adding new read-only regions will always be billed as standalone storage and will not count toward your included storage.

Row reads

Queries issued to your read-only region will contribute to your total billable row reads per month. To make it easier to track the cost, your invoice details will show a new line for rows read from any read-only region.

Try it out today

PlanetScale Portals is available in beta today. You can create a new read-only region in any PlanetScale database on a Base or Enterprise plan.

Sign up or log into your PlanetScale account and go to your database’s production branch page to add a region. Read more in the Portals docs.

If you have feedback, tweet at us @planetscale or post in our GitHub Discussion group.