cf-example-golang-hello-world

README

# Welcome

So, you've decided to try Codefresh? Welcome on board!

Using this repository we'll help you get up to speed with basic functionality such as: *compiling*, *testing* and *building Docker images*.

This project uses `golang` (or just `go`) to build an application which will eventually become a distributable Docker image.

## Example application

We'll use https://github.com/nuveo/prest[pREST] as an example application. pREST allows you to serve a RESTful API from any PostgreSQL database.
Have a look at the README.pREST.md file for more information about pREST.

## Looking around

In the root of this repository you'll find a file named `codefresh.yml`, this is our https://docs.codefresh.io/docs/what-is-the-codefresh-yaml[build descriptor] and it describes the different steps that comprise our process.
Let's quickly review the contents of this file:

### Testing

To test our code we use Codefresh's https://docs.codefresh.io/docs/steps#section-freestyle[Freestyle step].

The Freestyle step basically let's you say "Hey, Codefresh! Here's a Docker image. Create a new container and run these commands for me, will ya?"

```
  perform_tests:
    image: golang:latest
    working_directory: ${{main_clone}}
    description: Performing unit tests...
    commands:
      # Need to have the source in the correct GOPATH folder - let's do that
      - mkdir -p /go/src/github.com/${{CF_REPO_OWNER}}
      - ln -s /codefresh/volume/${{CF_REPO_NAME}} /go/src/github.com/${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}
      - cd /go/src/github.com/${{CF_REPO_OWNER}}/${{CF_REPO_NAME}} && go get
      - cd /go/src/github.com/${{CF_REPO_OWNER}}/${{CF_REPO_NAME}} && go test
```

The `image` field states which image should be used when creating the container (Similar to Travis CI's `language` or CircleCI`s `machine`).

The `commands` field is how you specify all the commands that you'd like to execute

### Building

To bake our application into a Docker image we use Codefresh's https://docs.codefresh.io/docs/steps#section-build[Build step].

The Build is a simplified abstraction over the Docker build command.

```
  build_image:
    type: build
    description: Building the image...
    image_name: ${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}
    tag: '${{CF_BRANCH}}'
```

Use the `image_name` field to declare the name of the resulting image (don't forget to change the image owner name from `${{CF_REPO_OWNER}}` to your own!).

### Launching

This is where it gets real! Let's use Codefresh's https://docs.codefresh.io/docs/steps#section-launch-composition[Launch Composition step] to run our composition within Codefresh!

Launching compositions within Codefresh means you have your very own staging area, at a click of a button!
```
  launch_composition:
    type: launch-composition
    description: Launching an environment from a composition...
    composition:
      version: '2'
      services:
        prest:
          image: '${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH}}'
          environment:
            - PREST_PG_HOST=postgres
            - PREST_PG_USER=prest
            - PREST_PG_PASS=prest
            - PREST_PG_DATABASE=prest
            - PREST_PG_PORT=5432
          depends_on:
            - postgres
          ports:
            - '3000'
        postgres:
          image: mbrung/postgres-no-volume
          environment:
            - POSTGRES_USER=prest
            - POSTGRES_DB=prest
            - POSTGRES_PASSWORD=prest
          ports:
            - '5432'
```

Using the `composition` field, we direct Codefresh to the location if the `docker-compose` file in our repository.

Once the Launch Composition step has completed successfully, you'll be able to review and share your running composition in the https://docs.codefresh.io/docs/share-environment-with-your-test[Environments page].

You'll now be able to either connect directly to pREST to perform RESTful opreations, or to the ephemereal Postgres database to create new schemas and tables for pREST to work with.

Now that we've gotten a grip on the flow, let's get cracking!

## Using This Example

To use this example:

. Fork this repository to your own Github account. (If you want to make changes and get the CI working on new commits)
. Log in to Codefresh using your Github account.
. Click the `Add Service` button.
. Select the forked repository. (Or paste in the the original repository's URL.)
. Select the `I have a codefresh.yml file` option.
. Complete the wizard.
. Rejoice!

Documentation

Overview

pREST - Serve a RESTful API from any PostgreSQL database

Install

go install github.com/nuveo/prest

Run

Params:

- PREST\_HTTP_PORT (default 3000)
- PREST\_PG_HOST (default 127.0.0.1)
- PREST\_PG_USER
- PREST\_PG_PASS
- PREST\_PG_DATABASE
- PREST\_PG_PORT
- PREST\_JWT_KEY

```
PREST_PG_USER=postgres PREST_PG_DATABASE=prest PREST_PG_PORT=5432 PREST_HTTP_PORT=3010 prest # Binary installed
```

Migrations

`--url` and `--path` flags are optional if pREST configurations already set

```bash
# env var for migrations directory
PREST_MIGRATIONS

# create new migration file in path
prest migrate --url driver://url --path ./migrations create migration_file_xyz

# apply all available migrations
prest migrate --url driver://url --path ./migrations up

# roll back all migrations
prest migrate --url driver://url --path ./migrations down

# roll back the most recently applied migration, then run it again.
prest migrate --url driver://url --path ./migrations redo

# run down and then up command
prest migrate --url driver://url --path ./migrations reset

# show the current migration version
prest migrate --url driver://url --path ./migrations version

# apply the next n migrations
prest migrate --url driver://url --path ./migrations next +1
prest migrate --url driver://url --path ./migrations next +2
prest migrate --url driver://url --path ./migrations next +n

# roll back the previous n migrations
prest migrate --url driver://url --path ./migrations next -1
prest migrate --url driver://url --path ./migrations next -2
prest migrate --url driver://url --path ./migrations next -n

# go to specific migration
prest migrate --url driver://url --path ./migrations goto 1
prest migrate --url driver://url --path ./migrations goto 10
prest migrate --url driver://url --path ./migrations goto v
```

TOML

Optionally the pREST can be configured by TOML file

- Set `PREST_CONF` environment variable with file path

```toml
migrations = "./migrations"

[http]
port = 6000

[jwt]
key = "mysecretkey"

[pg]
host = "127.0.0.1"
user = "postgres"
pass = "mypass"
port = 5432
database = "prest"
```

API`s

HEADER:

- To start JWT middleware the `PREST_JWT_KEY` environment variable must be set

```
Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
```

### Filter (WHERE) with JSONb field

```
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?FIELD->>JSONFIELD:jsonb=VALUE (filter)
```

### Select - GET

```
http://127.0.0.1:8000/databases (show all databases)
http://127.0.0.1:8000/schemas (show all schemas)
http://127.0.0.1:8000/tables (show all tables)
http://127.0.0.1:8000/DATABASE/SCHEMA (show all tables, find by schema)
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE (show all rows, find by database and table)
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?_page=2&_page_size=10 (pagination, page_size 10 by default)
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?FIELD=VALUE (filter)
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?_renderer=xml (JSON by default)
```

### Insert - POST

```
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE
```

JSON DATA:
```
{
    "data": {
        "FIELD1": "string value",
        "FIELD2": 1234567890
    }
}
```

### Update - PATCH/PUT

Using query string to make filter (WHERE), example:

```
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?FIELD1=xyz
```

JSON DATA:
```
{
    "data": {
        "FIELD1": "string value",
        "FIELD2": 1234567890
    }
}
```

### Delete - DELETE

Using query string to make filter (WHERE), example:

```
http://127.0.0.1:8000/DATABASE/SCHEMA/TABLE?FIELD1=xyz
```

## JOIN

Using query string to JOIN tables, example:

```
/DATABASE/SCHEMA/TABLE??_join=inner:users:friends.userid:$eq:users.id
```

Parameters:

1. Join type
1. Table
1. Table field 1
1. Operator (=, <, >, <=, >=)
1. Table field 2

Query Operators:

| Name | Description |
|-------|-------------|
| $eq | Matches values that are equal to a specified value.|
| $gt | Matches values that are greater than a specified value.|
| $gte | Matches values that are greater than or equal to a specified value.|
| $lt | Matches values that are less than a specified value.|
| $lte | Matches values that are less than or equal to a specified value.|
| $ne | Matches all values that are not equal to a specified value.|
| $in | Matches any of the values specified in an array.|
| $nin | Matches none of the values specified in an array.|