Datagram

Datagram is Gist for SQL. Quickly recall saved queries and transform results using JavaScript.

Datagram runs as a Docker container. It requires a host running Docker (or boot2docker on Mac), a query storage database (a SQLite file on the Datagram container or other database), and read-only access of your database to run the queries against.

Datagram is built as a Docker container and can run on any host supporting Docker. In the following example, we will install boot2docker to run this on a Mac host.

• Docker installed on a host (see installation instructions for your specific host):
  • Mac - https://docs.docker.com/installation/mac/
  • Ubuntu - https://docs.docker.com/installation/ubuntulinux/
  • Others - https://docs.docker.com/installation/
• Access to a database to report against
• Creation of a query database to store saved queries

Datagram is configured by two environment variables:

• QUERY_DATABASE_URL - The database that Datagram stores user written queries.
• REPORTING_DATABASE_URL - The database that Datagram runs queries against. Make sure this is being accessed via a read-only database account

These can be passed on the command line while running Datagram or as an environment file (such as datagram.env). An example datagram.env may look like:

QUERY_DATABASE_URL=sqlite:///datagram/storage/query_database.db
REPORTING_DATABASE_URL=mysql2://readonly:mypassword@database.mydomain.com/database_name

In this example, we will run two containers. One will be the storage for the query database and the other will be Datagram itself.

Run a data container to store the query database:

docker run -v /datagram/storage -d --name datagram-data tianon/true

Run the Datagram SQL migrations to create the initial database:

docker run --env-file $(pwd)/datagram.env --volumes-from datagram-data --rm polleverywhere/datagram datagram migrate

Run Datagram on default port 5000:

docker run --env-file $(pwd)/datagram.env --volumes-from datagram-data -p 5000:5000 -d --name datagram polleverywhere/datagram

You should now be able to visit datagram at your Docker host IP via port 5000. You can get the IP address of your boot2docker VM using boot2docker ip.

When developing on Datagram locally, you can run the application from Foreman without needing to build the application repeatedly in Docker.

Your local development environment should be configured using a .env file. You can copy the .env.sample file to .env and edit it according to your environment.

Run the application with Foreman:

bundle exec foreman start

Now visit Datagram at http://localhost:5000 and you should be ready to write some queries!

Datagram makes no assumptions about security, so make sure you do the following in a production environment:

1. Make sure the REPORTING_DATABASE_URL database is using an account with read-only permissions. You don't want users accidentally deleting data! Your database administrator should be able to set this.
2. Its highly recommended that you only make datagram accessible via HTTPS. Transfering your database content over the wire in the clear is not a good idea. We recommend running Datagram behind a load balancer or proxy that supports SSL.
3. Datagram provides no authentication or authorizaiton services. The easiest way to implement a username and password is via HTTP Basic authorization through either a rack middleware (building a new Docker image based on this one) or in the proxy configuration over HTTPS.

You've been warned!

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request