Skip to content

Commit

Permalink
Move from Travis to GitHub actions.
Browse files Browse the repository at this point in the history
Also, update our README with the latest info.

🎵 Now Playing: Really Over
🎵 Artist: Sub-Radio
🎵 Album: Past Selves
  • Loading branch information
paddycarver committed Feb 12, 2023
1 parent 7746bfd commit d09607e
Show file tree
Hide file tree
Showing 4 changed files with 81 additions and 22 deletions.
10 changes: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
- package-ecosystem: "gomod"
directory: "/"
schedule:
interval: "daily"
51 changes: 51 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
name: Run Tests
on:
push:
branches:
- main
paths-ignore:
- "*.md"
pull_request:
paths-ignore:
- "*.md"

jobs:
test:
name: Test
runs-on: ubuntu-latest
timeout-minutes: 20

strategy:
fail-fast: false
matrix:
go:
- '1.18'
- '1.19'
- '1.20'

steps:
- uses: actions/checkout@v3

- uses: actions/setup-go@v3
with:
go-version: ${{ matrix.go }}

- id: go-cache-paths
run: |
echo "::set-output name=go-build::$(go env GOCACHE)"
echo "::set-output name=go-mod::$(go env GOMODCACHE)"
- name: Go Build Cache
uses: actions/[email protected]
with:
path: ${{ steps.go-cache-paths.outputs.go-build }}
key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum') }}

- name: Go Mod Cache
uses: actions/[email protected]
with:
path: ${{ steps.go-cache-paths.outputs.go-mod }}
key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}

- name: Run Tests
run: go test ./... -race -v -count=1
9 changes: 0 additions & 9 deletions .travis.yml

This file was deleted.

33 changes: 20 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@

# About pan

`pan` is an SQL query building and response unmarshalling library for Go. It is designed to be compatible with MySQL and PostgreSQL, but should be more or less agnostic. Please let us know if your favourite SQL flavour is not supported.
`pan` is an SQL query building and response unmarshalling library for Go. It is designed to be compatible with MySQL, PostgreSQL, and SQLite, but should be more or less agnostic.
Please let us know if your favourite SQL flavour is not supported.

Pan is not designed to be an ORM, but it still eliminates much of the boilerplate code around writing queries and scanning over rows.

Pan’s design focuses on reducing repetition and hardcoded strings in your queries, but without limiting your ability to write any form of query you want. It is meant to be the smallest possible abstraction on top of SQL.
Pan’s design focuses on reducing repetition and hardcoded strings in your queries, but without limiting your ability to write any form of query you want.
It is meant to be the smallest possible abstraction on top of SQL.

Docs can be found on [GoDoc.org](https://godoc.org/darlinggo.co/pan).

If you're using pan, we encourage you to join the [pan mailing list](https://groups.google.com/a/darlinggo.co/group/pan), which will be our main mode of communication.
Docs can be found on [pkg.go.dev](https://pkg.go.dev/darlinggo.co/pan).

# Using pan

Expand Down Expand Up @@ -41,7 +41,8 @@ And you have a corresponding `Person` table:
+-----------+-------------+------+-----+---------+-------+
```

> **Note**: Unless you're using sql.NullString or equivalent, it's not recommended to allow `NULL` in your data. It may cause you trouble when unmarshaling.
> **Note**: Unless you're using sql.NullString or equivalent, it's not recommended to allow `NULL` in your data.
It may cause you trouble when unmarshaling.

To use that `Person` type with pan, you need it to fill the `SQLTableNamer` interface, letting pan know to use the `person` table in your database:

Expand Down Expand Up @@ -69,16 +70,18 @@ query.Comparison(p, "ID", "=", 1)
query.Flush(" ")
```

That `Flush` command is important: pan works by creating a buffer of strings, and then joining them by some separator character. Flush takes the separator character (in this case, a space) and uses it to join all the buffered strings (in this case, the `WHERE` statement and the `person_id = ?` statement), and then adds the result to its query.
That `Flush` command is important: pan works by creating a buffer of strings, and then joining them by some separator character.
Flush takes the separator character (in this case, a space) and uses it to join all the buffered strings (in this case, the `WHERE` statement and the `person_id = ?` statement), and then adds the result to its query.

> It's safe to call `Flush` even if there are no buffered strings, so a good practice is to just call `Flush` after the entire query is built, just to make sure you don't leave anything buffered.
The `pan.Columns()` function returns the column names that a struct's properties correspond to. `pan.Columns().String()` joins them into a list of columns that can be passed right to the `SELECT` expression, making it easy to support reading only the columns you need, maintaining forward compatibility—your code will never choke on unexpected columns being added.
The `pan.Columns()` function returns the column names that a struct's properties correspond to.
`pan.Columns().String()` joins them into a list of columns that can be passed right to the `SELECT` expression, making it easy to support reading only the columns you need, maintaining forward compatibility—your code will never choke on unexpected columns being added.

## Executing the query and reading results

```go
mysql, err := query.MySQLString() // could also be PostgreSQLString
mysql, err := query.MySQLString() // could also be PostgreSQLString or SQLiteString
if err != nil {
// handle the error
}
Expand All @@ -99,15 +102,18 @@ for rows.Next() {

## How struct properties map to columns

There are a couple rules about how struct properties map to column names. First, only exported struct properties are used; unexported properties are ignored.
There are a couple rules about how struct properties map to column names.
First, only exported struct properties are used; unexported properties are ignored.

By default, a struct property's name is snake-cased, and that is used as the column name. For example, `Name` would become `name`, and `MyInt` would become `my_int`.
By default, a struct property's name is snake-cased, and that is used as the column name.
For example, `Name` would become `name`, and `MyInt` would become `my_int`.

If you want more control or want to make columns explicit, the `sql_column` struct tag can be used to override this behaviour.

## Column flags

Sometimes, you need more than the base column name; you may need the full name (`table.column`) or you may be using special characters/need to quote the column name (`"column"` for Postgres, `\`column`\` for MySQL). To support these use cases, the `Column` and `Columns` functions take a variable number of flags (including none):
Sometimes, you need more than the base column name; you may need the full name (`table.column`) or you may be using special characters/need to quote the column name (`"column"` for Postgres, `\`column`\` for MySQL).
To support these use cases, the `Column` and `Columns` functions take a variable number of flags (including none):

```go
Columns() // returns column format
Expand All @@ -118,4 +124,5 @@ Columns(FlagFull, FlagDoubleQuoted) // returns "table"."column" format
Columns(FlagFull, FlagTicked) // returns `table`.`column` format
```

This behaviour is not exposed through the convenience functions built on top of `Column` and `Columns`; you'll need to use `Expression` to rebuild them by hand. Usually, this can be done simply; look at the source code for those convenience functions for examples.
This behaviour is not exposed through the convenience functions built on top of `Column` and `Columns`; you'll need to use `Expression` to rebuild them by hand.
Usually, this can be done simply; look at the source code for those convenience functions for examples.

0 comments on commit d09607e

Please sign in to comment.