Akiban Server add-on documentation

Akiban Server is an add-on for providing a cloud data service for real-time object access and complex queries.

Data access is provided via JSON encoding of entities or SQL for advanced queries.

Akiban Server is accessible via REST over HTTP or SQL using the Postgres network protocol. A Ruby client library is supported for ActiveRecord.

Provisioning the add-on

Akiban Server can be attached to a Heroku application via the CLI:

A list of all plans available can be found [here](http://addons.heroku.com/akibanserver).

:::term
$ heroku addons:add akibanserver
-----> Adding akibanserver to sharp-mountain-4005... done, v18 (free)

Once Akiban Server has been added, the following settings will be available in the app configuration.

AKIBANSERVER_DATABASE_URL: the connection string for SQL access.
AKIBANSERVER_REST_URL: the URL for RESTful access.

These can be confirmed using the heroku config:get command.

:::term
$ heroku config:get AKIBANSERVER_DATABASE_URL
postgres://79a21082_5f50_4549_997f_dc741964a5bb:[email protected]:15432/79a21082_5f50_4549_997f_dc741964a5bb

After installing Akiban Server the application should be configured to use these credentials as outlined below.

Local setup

Environment setup

After provisioning the add-on itâ��s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable itâ��s also possible to set local environment variables using `export AKIBANSERVER_DATABASE_URL=value`.

Use Foreman to configure, run and manage process types specified in your appâ��s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add all the AKIBANSERVER_ values retrieved from heroku config to .env.

:::term
$ heroku config -s | grep AKIBANSERVER_ >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: `echo .env >> .gitignore`.

Using with Rails 3.x

Akiban implements a full ANSI SQL database that is compatible with ActiveRecord.

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Akiban Server ActiveRecord client library.

:::ruby
gem 'activerecord-akiban-adapter', :git => 'git://github.com/akiban/activerecord-akiban-adapter.git'

Update application dependencies with bundler.

:::term
$ bundle install

Get configuration credentials.

:::term
$ heroku config:get AKIBANSERVER_DATABASE_URL
postgres://79a21082_5f50_4549_997f_dc741964a5bb:[email protected]:15432/79a21082_5f50_4549_997f_dc741964a5bb

Update config/database.yml to match the database / username, password, host and port.

:::yaml
development:
  adapter: akiban
  encoding: UTF-8
  database: 79a21082_5f50_4549_997f_dc741964a5bb
  pool: 5
  username: 79a21082_5f50_4549_997f_dc741964a5bb
  password: 5f5fcf19637bd741e859
  host: db1.akiban.com
  port: 15432

Using with Node.js: JSON via REST.

The easiest way to get data from Akiban into Node is using the REST API, which can fetch / store individual entities or run complex SQL queries.

For example, with the request package in package.json.

:::json
{
  ...
  "dependencies": {
    ...
    "request": "latest"
  },
  ...
}

Add a request to the URL supplied by the addon.

:::javascript
function akiban_rest(path) {
  return { url: process.env.AKIBANSERVER_REST_URL + path,
      json: true };
}

app.get('/vrest', function(req, resp) {
          request.get(akiban_rest('/version'), function(error, response, body) {
                        var vers = body[0];
                        resp.send(vers.server_name + " " + vers.server_version);
                      });
        });

See REST API Reference for complete documentation on the available REST endpoints.

Using with Node.js: SQL via Postgres.

If preferred, it is equally possible to access Akiban using SQL.

For this, you will need the Postgres client library in package.json.

:::json
{
  ...
  "dependencies": {
    ...
    "pg": "latest"
  },
  ...
}

Add a request to the URL supplied by the addon.

:::javascript
var pg = require('pg');
...

app.get('/vsql', function(req, resp) {
          pg.connect(process.env.AKIBANSERVER_DATABASE_URL, function(err, client) {
                       console.log(err);
                       var query = client.query('SELECT server_name, server_version FROM information_schema.server_instance_summary');
                       query.on('row', function(row) {
                                  resp.send(row.server_name + " " + row.server_version)
                                });
                     });
        });

Note: Akiban uses the Postgres network protocol, but the database is not Postgres-based. Do not expect all Postgres idioms to work. See the SQL Reference for details on the Akiban dialect of ANSI SQL.

It also works to use some combination of SQL and REST. The data is the same.

Dashboard

For more information on the features available within the Akiban Server dashboard please see the docs at [akiban.com](http://www.akiban.com/docs.html).

The Akiban Server dashboard allows you to view or define the entity data model.

The dashboard can be accessed via the CLI:

:::term
$ heroku addons:open akibanserver
Opening akibanserver for sharp-mountain-4005â�¦

or by visiting the Heroku apps web interface and selecting the application in question. Select Akiban Server from the Add-ons menu.

Removing the add-on

Akiban Server can be removed via the CLI.

This will destroy all associated data and cannot be undone!

:::term
$ heroku addons:remove akibanserver
-----> Removing akibanserver from sharp-mountain-4005... done, v20 (free)

Before removing Akiban Server a data export should be dowloaded from the Backups section for the deployment in the Akiban Server dashboard.

Support

All Akiban Server support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at [email protected].

MMcM/gist:5208966