enspirit/dbagent repository overview

⁠DbAgent, a ruby tool to migrate, spy and seed PostgreSQL databases

DbAgent helps managing a relational database lifecyle through three main tools:

• Migrations: powered by Sequel⁠, migrate as simply as rake db:migrate. Supports both superuser and normal user migrations.

• Spy: using Shemaspy⁠, get your database schema browsable at any moment, through a simple web interface.

• Seed: maintain, install and flush database content as datasets, organized hierarchically in .json files. Very handy for automated tests, for instance.

⁠Get started using Docker

DbAgent is expected to be used as its Docker agent, available as enspirit/dbagent. Simply mount migrations and data folders, and you're ready to go.

See the examples folder for details.

⁠Available environment variables

• DBAGENT_ROOT_FOLDER Main folder where data, migrations and viewpoints can be found
• DBAGENT_LOGLEVEL Log level to use for dbagent messages (defaults to WARN)
• DBAGENT_LOGSQL Low Sequel's SQL queries (defaults to no)
• DBAGENT_ADAPTER Sequel's adapter (defaults to postgres)
• DBAGENT_HOST Database server host (defaults to localhost)
• DBAGENT_PORT Database server port (defaults to 5432)
• DBAGENT_DB Database name (defaults to suppliers-and-parts)
• DBAGENT_USER Database user (defaults to dbagent)
• DBAGENT_PASSWORD Database password (defaults to dbagent)
• DBAGENT_SOCKET Database server socket (if host/port is not used)
• DBAGENT_SUPER_USER Superuser name (postgres only)
• DBAGENT_SUPER_DB Superuser database (postgres only)
• DBAGENT_SUPER_PASSWORD Superuser password (postgres only)
• DBAGENT_VIEWPOINT Bmg viewpoint (class name) when using db:flush

⁠Available rake tasks

The following rake tasks helps you managing the database. They must typically be executed on the docker container.

rake db:check-seeds    # Checks that all seeds can be installed correctly
rake db:create         # Creates an fresh new user & database (USE WITH CARE)
rake db:drop           # Drops the user & database (USE WITH CARE)
rake db:flush[to]      # Flushes the database as a particular data set
rake db:migrate        # Runs migrations on the current database
rake db:ping           # Pings the database, making sure everything's ready for migration
rake db:rebuild        # Rebuilds the database from scratch (USE WITH CARE)
rake db:repl           # Opens a database REPL
rake db:seed[from]     # Seeds the database with a particular data set
rake db:spy            # Dumps the schema documentation into database/schema
rake db:backup         # Makes a database backup to the backups folder
rake db:restore[match] # Restore the last matching database backup file from backups folder
rake db:revive         # Shortcut for both db:restore and db:migrate

⁠Available webservices

GET  /schema/                # Browser the database schema (requires a former `rake db:spy`)
POST /seeds/install?id=...   # Install a particular dataset, id is the name of a folder in `data` folder
POST /seeds/flush?id=...     # Flushes the current database content as a named dataset

⁠Hacking on dbagent

⁠Installing the library

bundle install

⁠Preparing your computer

The tests require a valid PostgreSQL installation with the suppliers-and-parts database installed. A dbagent user would be needed on the PostgreSQL installation to bootstrap the process.

sudo su postgres -c 'createuser --createdb dbagent -P'

DbAgent tries to connect to the suppliers-and-parts with a dbagent/dbagent user/password pair by default. If you change the database name, user, or password please adapt the environment variables accordingly in the commands below.

⁠Installing the example database

DBAGENT_ROOT_FOLDER=examples/suppliers-and-parts bundle exec rake db:create db:migrate db:seed['base']

⁠Contributions

⁠Running test

To run the test you need to have Docker on your computer.

Run:

make test

Don't forget to delete created ressources for the tests bun running:

make clean