Metadata-Version: 2.0
Name: tunneler
Version: 0.1.1490760674
Summary: Connect to databases via ssh tunnel
Home-page: https://github.com/govau/tunneler
Author: Robert Lechte
Author-email: robert.lechte@digital.gov.au
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: paramiko
Requires-Dist: pyyaml
Requires-Dist: six
Requires-Dist: sqlbag
Requires-Dist: sshtunnel
Provides-Extra: pg
Requires-Dist: psycopg2; extra == 'pg'

tunneler: Connect to databases via ssh tunnel
=============================================

A command tool and library to connect to databases with minimal fuss.

To install:

.. code-block:: shell

    $ pip install tunneler

You will probably also need the database drivers for your preferred database. To install the postgres ones automatically when you install ``tunneler``, do this:

.. code-block:: shell

    $ pip install tunneler[pg]

To run:

.. code-block:: shell

    $ tunneler name_of_task name_of_connection

As the above command shows, there are two concepts to understand when running tunneler, ``connections`` and ``tasks``.

Define connections in a ``connections.yaml`` file in your current directory, as follows:

.. code-block:: yaml

    prod:
      remote_host: publicjumpboxservername
      ssh_username: username
      ssh_pkey: |
        -----BEGIN RSA PRIVATE KEY-----
        .......................................
        .......................................
        -----END RSA PRIVATE KEY-----
      private_dburl: postgres://username:password@privatedbservername/databasename
      local_port: 5433

    dev:
      .....

You can also specify an ssh_config variable in the config. ``tunneler`` will then use the values from that hosts ssh config. An example:

.. code-block:: yaml

    prod:
      ssh_config: prod-jumpbox
      private_dburl: postgres://username:password@privatedbservername/databasename
      local_port: 5433

    dev:
      .....

This will use the remote host/username/private key specified in your existing ssh config so you don't need to repeat them in the config file

Tunneler will use this information to set up a local tunneled post where you can access this database directly.

A connection URL to this local port will then be provided to each ``task``.

There are three inbuilt tasks:

  - test_connection (run this one to check your config is correct)
  - do_full_pg_dump (assumes you have pg_dump installed)
  - do_schema_pg_dump (also assumes you have pg_dump installed)

So for example to dump the production schema we'd run the following command:

.. code-block:: shell

    $ tunneler do_schema_pg_dump prod

Custom tasks
------------

Want to define your own tasks? Simply create a tasks.py file (or module) in the current directory.

Define a top level method in this file that accepts a connection url, and that method name will be available as a task.

For instance, the test connection task could be re-implemented as follows:

.. code-block:: python

    from sqlbag import S

    def test_connection_custom(dburl):
        with S(dburl) as s:
            s.execute('select 1')

You'd then run this as follows:

.. code-block:: shell

    $ tunneler test_connection_custom prod

Pretty simple.


