dockerql

A SQL-like interface for docker registries.

Early stage project

Why

SQL-like query interface is still one of the easiest to understand methods to query any collection of data. Dockerql brings this familiar interface to the docker registry world.

What

Dockerql provides a read-only SQL query interface to docker registries.

Ket features:

• Supports DockerHub, Amazon Container Registry, and Google Container Registry.
• Handle in a uniform way the various authentication flow for each docker registry implementation.
• Developed in JavaScript.
• NPM Package: Available for use within any node application.
• Local Service: Clone from gihub and run as a local service.
• DockerHub: Available from DockerHub as a prepackaged docker image.

Getting started - Node.js

• Install dockerql:

  npm install -i dockerql --save

• Use dockerql:

  import * as dockerql from 'dockerql'
  ...
  
    try {
        // setup the dockerql option, for now this means loglevel
        dockerql.init()
  
        // connect to a registry, in this case dockerhub with anonymous access
        await dockerql.connect({ name: "dockerhub", type: "dockerhub" })
  
        // select the list of repos
        const rsp = await dockerql.query(`SELECT repo, stars, pulls FROM repos`)
  
        // catch errors
        if (rsp.code !== 200) {
            console.error(rsp.message)
            return
        }
  
        ...
    } catch (err) {
        console.log("Error ", err)
    }
    ...

See the full simple example, or try it in replit.

Getting started - Service

dockerql can be run as a standalone service exposing a query endpoint as well as an npm package.

Here are few different ways to quickly get started with running dockerql as a service.

1. Run as a docker container.
2. Run as a local service.
3. Set up the service access to your registries.

Supported registry types

Currently supported:

1. Set up access to Dockerhub
2. Set up access to Amazon Elastic Container Registry (ECR)
3. Set up access to Google Container Registry (GCR)

Documentation

• docekrql docs.

Folder structure

dockerQL
|
└─ examples
|  └─ simple
| 
└─ lib # packaging of dockerQL as an npm package
| 
└─ server # api server servicing dockerql via REST api  

CHANGELOG

0.1.9 (April-4-2021)

• Simplify local server start.
• Add tests for dockerhub.

0.1.8 (April-2-2021)

• Change error handling to throw.
• Add tests for init and connect.

0.1.7 (March-31-2021)

• Changes to readme.

0.1.6 (March-31-2021)

• A second fix for npm published.

0.1.5 (March-31-2021)

• Fix issue with files excluded from the npm published.

0.1.4 (March-28-2021)

• Stabilization release.

0.1.0 (March-15-2021)

• A complete refactor of the package organization. Creating a new lib and server separate projects.
• Change default conf file to /var/dockerql/config.json.
• Change optional env variable from "DOCKER_REGISTRIES" to "DOCKERQL_CONF".
• Change optional env variable from "DOCKER_REGISTRIES_FILE" to "DOCKERQL_FILE".
• Updated error handling.
• Updated unit test framwork.

0.0.13 (Feb-4-2021)

• Package dockerql as a library and move the server file to a sub folder.

0.0.12 (Jan-24-2021)

• Change tag field to tags. In ECR and GCR return the array of tags, in Dockerhub, return an array of a single entry.
• Add registry specific columns:
• Dockerhub: repos added stars and pulls.
• Dockerhub: images added architecture and os.
• ECR: repos added arn, uri, scanOnPush, imageImmutability, and created.

0.0.11 (Jan-16-2021)

• Update base image to node-15.5.1-slim.
• Build a first set of tests
• Change query parameter to be sql (was previousely query)

0.0.10 (Jan-10-2021)

• Verify support for public repos in dockerhub and gcr.
• Update documentation to highlight specific SQL statement to access public repos.

0.0.7 (Jan-2-2021)

• Happy New Year!
• Add support for ECR.

0.0.6 (Dec-26-2020)

• Better project organization with RegistryType as a class.
• Handling of more complex SELECT statements by using alasql to process the resultset post initial query.