diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..615dfde --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" + - package-ecosystem: "gomod" + directory: "/" + schedule: + interval: "daily" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..4575e79 --- /dev/null +++ b/.github/workflows/test.yml @@ -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/cache@v3.2.2 + with: + path: ${{ steps.go-cache-paths.outputs.go-build }} + key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum') }} + + - name: Go Mod Cache + uses: actions/cache@v3.2.2 + 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 diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 59288de..0000000 --- a/.travis.yml +++ /dev/null @@ -1,9 +0,0 @@ -language: go - -go: - - 1.7 - - 1.8 - - 1.9 - - "1.10" - - "1.11" - - tip diff --git a/README.md b/README.md index fb583d0..9fffdbe 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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: @@ -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 } @@ -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 @@ -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.