Heroku Postgres は Heroku 上で動く SQL database service です。add-on として管理されており、提供されています。また、Heroku Postgres は PostgreSQL driver のあるどんな言語からも accessible です。具体的には、Heroku によってサポートされる全ての言語、フレームワーク（Java, Ruby, Python, Scala, Play, Node.js, PHP, Go, and Clojure）から Heroku Postgres にアクセスできます。

Heroku CLI を通じて実行できる様々な management commands に加えて、この Heroku Postgres は 「”web dashboard” という dataclips を create する機能」と「その他の追加的なサービス」をデータベースサービス上で実装してます。

Provisioning the add-on

作ったアプリケーションを Heroku上で実行できる entity にコンパイルする buildpacksというのがありますが、多くの buildpacks は自動的に Heroku Postgres instance を提供してくれます。

Your language’s buildpack documentationのページで、どの add-ons　が自動的に提供されているのか確認できます。また、

heroku addons

を使えばアプリケーションに 提供された database を持っているか、どのプランなのか、を確認できます（下のように見れます）。

Add-on                             Plan      Price  State  
─────────────────────────────────  ────────  ─────  ───────
scheduler (scheduler-round-96601)  standard  free   created
 └─ as SCHEDULER

The table above shows add-ons and the attachments to the current app (young-tor-55488) or other apps.

もしprovisionされたデータベースがない、あるいは既存のデータベースをアップグレード、あるいはデータベースを新規作成したいなら、CLIからつくれます。

Create a new database

Heroku Postgres にはサービスのtier、レベルにまたがって、色々と種類があります(hobby, standard, premium, and enterprise.)。Choosing the Right Heroku Postgres Planを参考にしてプランを選択しましょう。もし最初のプランを変更したくなればスケーリングできます。

Heroku Postgres は CLI で以下のコマンドを叩けば任意の Heroku application に追加できます。

heroku addons:create heroku-postgresql:<PLANNAME>

例えば hobby-dev plan database を provision するなら、こうなります。

$ heroku addons:create heroku-postgresql:hobby-dev
Adding heroku-postgresql:hobby-dev to sushi... done, v69 (free)
Attached as HEROKU_POSTGRESQL_RED
Database has been created and is available

もし hobby-basic plan database を provision するならこうです。

$ heroku addons:create heroku-postgresql:hobby-basic

プランによってかかる5分くらいかかるかもしれません。pg:wait で状態を track できます。

$heroku pg:wait
Waiting for database HEROKU_POSTGRESQL_RED... done

一度 Heroku Postgres が DATABASE_URL か HEROKU_POSTGRESQL_COLOR_URL に加えられると、 app configuration で setting が使えるようになり、 setting は 新しく provision されたHeroku Postgres serviceへアクセスする URL を含みむようになります。

もし作成したデータベースがそのアプリにとって最初のものなら、データベースに対して DATABASE_URL が付与されます。そうでなければ、HEROKU_POSTGRESQL_COLOR_URLが作成されます。 heroku config で色々確認できます。環境変数とかも。下のは「最初のアプリ」ではないケースなので、”HEROKU_POSTGRESQL” で grep してますね。もし初めてのものなら、heroku config -s | grep DATABASE_URL とかで確認できます。

heroku config -s | grep HEROKU_POSTGRESQL
HEROKU_POSTGRESQL_RED_URL=postgres://user3123:passkja83kd8@ec2-117-21-174-214.compute-1.amazonaws.com:6212/db982398

補足： –as という flag で add-on が使う alias を決められます。これで add-on が加える変数の名前を決められます。

$ heroku addons:create heroku-postgresql:hobby-dev --as USERS_DB
Adding heroku-postgresql:hobby-dev to sushi... done, v69 (free)
Attached as USERS_DB
Database has been created and is available  
$ heroku config -s | grep USERS_DB
USERS_DB_URL=postgres://user3123:passkja83kd8@ec2-117-21-174-214.compute-1.amazonaws.com:6212/db982398

Establish primary DB

上で「２つ目以降は HEROKU_POSTGRESQL_COLOR_URL になるけど –as で変えられるよ」と述べました。Heroku では、primary database の位置を保存するには DATABASE_URL を config var として使うことを推奨しています。single-database setups では先ほど述べたように、新しいデータベースは既に DATABASE_URL を持っています。

もし一つのアプリに複数のデータベースを持たせたいなら、以下のように primary database をセットします。

$ heroku pg:promote HEROKU_POSTGRESQL_RED
Promoting HEROKU_POSTGRESQL_RED_URL to DATABASE_URL... done

この段階で、空っぽな PostgreSQL database が与えられます。もし既存のデータソースからデータを populate したい場合は、import instructions の項目を見るか、アプリに接続する為に、この記事の言語ごとに記された導入方法に従ってください。

Sharing Heroku Postgres between applications

ちなみに、Heroku Postgres はアプリ間で共有できます。

$ heroku addons:attach my-originating-app::DATABASE --app sushi
Attaching postgresql-addon-name to sushi... done
Setting HEROKU_POSTGRESQL_BRONZE vars and restarting sushi... done, v1

データベースは色を表す単語がくっつきます。上の例では HEROKU_POSTGRESQL_BRONZE となってますが、場合によって変わります。 シェアしないので飛ばします。

Version support and legacy infrastructure

実行したい Postgres のバージョンは Heroku CLI の中で –version を使って確認できます。PostgreSQL project は年単位で新しい主流となるバージョンをリリースしてます。それぞれのバージョンは、一度リリースされれば、すぐ後に　Heroku Postgres がサポートします。Heroku Postgres は少なくともその時ごとに３つのバージョンをサポートいます。現在サポートしているバージョンは以下のとおりです。

• 9.6 (default)
• 9.5
• 9.4
• 9.3
• 9.2 (deprecated)

３つのバージョンをサポートしているということは、ユーザーは三年ごとにシステムをアップグレードしなくてはなりません。しかし、最新のバージョンの恩恵を受けたければ、いつでもアップグレードが可能です。

Heroku はときたま、Heroku のインフラ上の古いバージョン (Legacy Infrastructure) を deprecate します。なんでこんなことをするかというと、データベースの下で走ってるOSがセキュリティーのアップデートを受けられなくなったり、OSへのサポートが時代のために意味を成さなくなったり（必要なパッチなどが利用不可だったり）、サーバーのインスタンスが現行のインフラと大きくことなりサポートが現実的でなくなるかもしれないからです。データベースが legacy infrastructure で走っているかを確認するには、pg:info を使います・

$ heroku pg:info

=== HEROKU_POSTGRESQL_MAROON_URL (DATABASE_URL)
Plan:           Ronin
Status:         Available
Data Size:      26.1 MB
Tables:         5
PG Version:     9.5.3
Connections:    2
Fork/Follow:    Available
Rollback:       Unsupported
Created:        2012-05-02 21:54 UTC
Maintenance:    not required (Mondays 23:00 to Tuesdays 03:00 UTC)
Infrastructure: Legacy

Migration of deprecated databases

飛ばします。急には変えないけど、型落ちしたら変えてね、という話。

Performance analytics

飛ばします。

Local setup

これも飛ばします。ローカルでも動かせるようにね、という話と、各OSでの Postgres のインストールの話。

export DATABASE_URL=postgres:///$(whoami)

Set up Postgres on Linux

乱暴ですが、sudo でインストール、which で場所確認、psqlで確認です。

sudo apt-get install postgresql
If you do not have a package manager on your distribution or the Postgres package is not available, install Postgres on Linux using one of the Generic installers.
The psql client will typically be installed in /usr/bin:
$ which psql
/usr/bin/psql
and the command should work correctly:
$ psql
psql (9.3.5)
Type "help" for help.
maciek# \q

ちなみに psql でロールが存在しないと怒られた。heroku pg:psql ではちゃんと接続できてそう。 ここで詰まってます。 ロール(ユーザー)の作成 sudo su – postgres で入って psql で起動して select rolname from pg_roles; をすると postgres しかない。

Using the CLI

Connecting in Python

to use PostgreSQL as your database in Python applications you will need to use the psycopg2 package.

$ pip install psycopg2
$ pip freeze > requirements.txt
And use this package to connect to DATABASE_URL in your code:
import os
import psycopg2
import urlparse

urlparse.uses_netloc.append("postgres")
url = urlparse.urlparse(os.environ["DATABASE_URL"])

conn = psycopg2.connect(
    database=url.path[1:],
    user=url.username,
    password=url.password,
    host=url.hostname,
    port=url.port
)

で使える。connさえできれば、あとはなんとでも。だから、あとはテーブルを作って、とかの作業。 と思ったら使えません。

注釈 urlparse モジュールは、Python 3 では urllib.parse にリネームされました。 2to3 ツールが自動的にソースコードの import を修正します。

2to3 使って差分取って直します。