Project

pg_rest

0.0
No release in over a year
REST API for remote PostgreSQL database migrations.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
 Dependencies

Runtime

>= 0
~> 6.1.4, >= 6.1.4.1
 Project Readme

PgRest

PgRest is a REST API for managing Active Record database migrations.

Perform Active Record database migrations to manage database schema migrations.

Features

PgRest supports the following database migrations using a REST API:

  • Add table
  • Drop table
  • Add column
  • Remove column

PgRest operations are secured using an API token.

Installation

Add this line to your application's Gemfile:

gem 'pg_rest'

And then execute:

$ bundle

Mount the PgRest API by updating your config/routes.rb file:

Rails.application.routes.draw do
  ...
  mount PgRest::Engine, at: "/pg-rest"
  ...
end 

You can also configure PgRest with an initializer by creating a file at config/initializers/pg_rest.rb.

# Place file at config/initializers/pg_rest.rb

PgRest.tap |config|
  config.api_token = ENV['PG_REST_API_TOKEN']
end 

Requirements

PgRest requires Ruby on Rails and PostgreSQL, and below are recommended versions:

  • Rails 6+
  • Ruby 2.7.4+
  • Active Record supported database.

Documentation

PgRest is designed to remotely create common database migration tasks using a REST API.

Schema

Your database schema is available in order to inspect available tables and column data.

GET /pg-rest

You can inspect any specific table using the schema endpoint:

GET /pg-rest/tables/<table_name>

Create table

Create a table migration.

POST /pg-rest/tables

Parameters

Parameter Type Description
name string The name of the database table.

Drop table

Drop a database table.

DELETE /pg-rest/tables/:table_name

Parameters

Parameter Type Description
table_name string The name of the database table to drop.

Add column

Add a database column.

POST /pg-rest/tables/<table_name>/columns

Parameters

Parameter Type Description
table_name string The name of the table.
name string The column name.
type string Active Record supported database field type.
default boolean The default value. Defaults to null
array boolean The name of the database table.
foreign_key boolean Column is a foreign_key. Defaults to false.
primary_key boolean Column is a primary_key. Defaults to false.

Remove column

Remove a database column.

POST /pg-rest/tables/<table_name>/<column_name>

Parameters

Parameter Type Description
table_name string The name of the table.
column_name string The name of the column to remove.

REST API client

PgRest also supports a ruby client for handling the API requests.

You can initialize the PgRest client using:

pg_client = PgRest::Api.new(api_key: <API_KEY>, api_url: <API_URL>)

Database migrations using PgRest API client

Create table:

pg_client.create_table(table_name: <TABLE_NAME>)

Drop table:

pg_client.drop_table(table_name: <TABLE_NAME>)

Add table column:

pg_client.add_column(
  table_name: <TABLE_NAME>,
  name: <COLUMN_NAME>,
  type: <COLUMN_TYPE>,
  default: <DEFAULT_VALUE>,
  array: <IS_ARRAY>,
  primary_key: <IS_PRIMARY_KEY>,
  foreign_key: <IS_FOREIGN_KEY>,
)

Remove table column:

pg_client.remove_column(
  table_name: <TABLE_NAME>, 
  name: <COLUMN_NAME>
)

API Token Authentication

The PgRest API is secured using an API token.

# /config/initializers/pg_rest.rb

PgRest.tap do |config|
  config.api_token = ENV['PG_REST_API_TOKEN']  
  ...
end 

Contributing

Contributions are welcome by issuing a pull request at our github repository: https:/github.com/dash-api/pg-rest

License

The gem is available as open source under the terms of the MIT License.