pgctl: the playground controller¶

Distribute & Pip¶

Installing pgctl is simple with pip, just run this in your terminal:

$ pip install pgctl

Get the Code¶

pgctl is actively developed on GitHub, where the code is always available.

You can either clone the public repository:

$ git clone git://github.com/yelp/pgctl.git

Download the tarball:

$ curl -OL https://github.com/yelp/pgctl/tarball/master

Or, download the zipball:

$ curl -OL https://github.com/yelp/pgctl/zipball/master

Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily:

$ python setup.py install

Usage¶

pgctl has eight basic commands: start, stop, restart, debug, status, log, reload, config

$ pgctl start <service=default>

$ pgctl stop <service=default>

$ pgctl restart <service=default>

$ pgctl debug <service=default>

$ pgctl status <service=default>
<service> pid(<PID>) -- up (0 seconds)

$ pgctl log <service=default>

$ pgctl reload <service=default>

$ pgctl config <service=default>

Setting up¶

The minimal setup for pgctl is a playground directory containing the services you want to run. A service consists of a directory with a run script. The script should run in the foreground.

$ cat playground/date/run
date > now.date

Once this is in place, you can start your playground and see it run.

$ pgctl start
$ pgctl logs
[webapp] Serving HTTP on 0.0.0.0 port 36474 ...

$ curl

Aliases¶

With no arguments, pgctl start is equivalent to pgctl start default. By default, default maps to a list of all services. You can configure what default means via playground/config.yaml:

aliases:
    default:
        - service1
        - service2

You can also add other aliases this way. When you name an alias, it simply expands to the list of configured services, so that pgctl start A-and-B would be entirely equivalent to pgctl start A B.

Submodules¶

pgctl.cli module¶

class pgctl.cli.PgctlApp(config=<frozendict {u'services': (u'default', ), u'pgdir': u'playground', u'pgconf': u'conf.yaml', u'pghome': u'~/.run/pgctl'}>)¶

Bases: object

aliases¶

A dictionary of aliases that can be expanded to services

all_services¶

Return a tuple of all of the Services.

Returns:	tuple of Service objects

app_invariants()¶

The are the things we want to be able to say “always” about.

commands = (<function start at 0x7f7868ec8a28>, <function stop at 0x7f7868ec8aa0>, <function status at 0x7f7868ec8b90>, <function restart at 0x7f7868ec8c08>, <function reload at 0x7f7868ec8c80>, <function log at 0x7f7868ec8cf8>, <function debug at 0x7f7868ec8d70>, <function config at 0x7f7868ec8de8>)¶

config()¶

Print the configuration for a service

debug()¶

Allow a service to run in the foreground

idempotent_supervise()¶

ensure all services are supervised starting in a down state by contract, running this method repeatedly should have no negative consequences

log()¶

Displays the stdout and stderr for a service or group of services

pgdir¶

Retrieve the set playground directory

pghome¶

Retrieve the set pgctl home directory.

By default, this is “$XDG_RUNTIME_DIR/pgctl”.

reload()¶

Reloads the configuration for a service

restart()¶

Starts and stops a service

service_by_name(service_name)¶

Return an instantiated Service, by name.

service_names¶

services¶

Return a tuple of the services for a command

Returns:	tuple of Service objects

services_string¶

start()¶

Idempotent start of a service or group of services

status()¶

Retrieve the PID and state of a service or group of services

stop()¶

Idempotent stop of a service or group of services

unsupervise()¶

pgctl.cli.exec_(argv, env=None)¶

Wrapper to os.execv which runs any atexit handlers (for coverage’s sake). Like os.execv, this function never returns.

pgctl.cli.main(argv=None)¶

pgctl.cli.parser()¶

Module contents¶