LBRYCommunity/sqlboiler
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity

Readme - headers and more organization

Browse source
This commit is contained in:
Patrick O'brien 2016-08-30 20:38:29 +10:00
parent e41b223838
commit ec4b7163c2
1 changed files with 151 additions and 101 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

252
README.md
View file

@ -12,6 +12,13 @@ That means you must first create your database schema. Please use something
like goose or some other migration tool to manage this part of the database's
lifecycle.
## Why?
Well...
---
## About SQL Boiler
#### Features
@ -37,7 +44,9 @@ lifecycle.
**Note:** Seeking contributors for other database engines.
#### Example Queries
#### Small Taste
For a comprehensive list of available operations and examples please see [Features & Examples](#features-examples).
```go
import (
@ -95,50 +104,87 @@ if err != nil {
}
fmt.Println(len(users.R.FavoriteMovies))
```
#### Requirements & Recommendations
###### Required
---
## Requirements & Pro Tips
### Requirements
* Table names and column names should use `snake_case` format.
* At the moment we only support `snake_case` table names and column names. This
is a recommended default in Postgres, we can reassess this for future database drivers.
* At the moment we require `snake_case` table names and column names. This
is a recommended default in Postgres. We can reassess this for future database drivers.
* Join tables should use a *composite primary key*.
* For join tables to be used transparently for relationships your join table must have
a *composite primary key* that encompasses both foreign table foreign keys. For example, on a
join table named `user_videos` you should have: `primary key(user_id, video_id)`, with both `user_id`
and `video_id` being foreign key columns to the users and videos tables respectively.
###### Optional
### Pro Tips
* Foreign key column names should end with `_id`.
* Foreign key column names in the format `x_id` will generate clearer method names.
This is not a strict requirement, but it is advisable to use this naming convention whenever it
makes sense for your database schema.
It is advisable to use this naming convention whenever it makes sense for your database schema.
* If you never plan on using the hooks functionality you can disable generation of this
feature using the `--no-hooks` flag. This will save you some binary size.
## Automatic CreatedAt/UpdatedAt
---
If your generated SQLBoiler models package can find columns with the
names `created_at` or `updated_at` it will automatically set them
to `time.Now()` in your database, and update your object appropriately.
To disable this feature use `--no-auto-timestamps`.
## Getting started
**Note:** You can set the timezone for this feature by calling `boil.SetLocation()`
#### Download
#### Overriding Automatic Timestamps
```shell
go get -u -t github.com/vattle/sqlboiler
```
* **Insert**
* Timestamps for both `updated_at` and `created_at` that are zero values will be set automatically.
* To set the timestamp to null, set `Valid` to false and `Time` to a non-zero value.
This is somewhat of a work around until we can devise a better solution in a later version.
* **Update**
* The `updated_at` column will always be set to `time.Now()`. If you need to override
this value you will need to fall back to another method in the meantime: `boil.SQL()`,
overriding `updated_at` in all of your objects using a hook, or create your own wrapper.
* **Upsert**
* `created_at` will be set automatically if it is a zero value, otherwise your supplied value
will be used. To set `created_at` to `null`, set `Valid` to false and `Time` to a non-zero value.
* The `updated_at` column will always be set to `time.Now()`.
#### Configuration
Create a configuration file. Because the project uses [viper](github.com/spf13/viper), TOML, JSON and YAML
are all supported. Environment variables are also able to be used.
We will assume TOML for the rest of the documentation.
The configuration file should be named `sqlboiler.toml` and is searched for in the following directories in this
order:
- `./`
- `$XDG_CONFIG_HOME/sqlboiler/`
- `$HOME/.config/sqlboiler/`
We require you pass in the `postgres` configuration via the configuration file rather than env vars.
There is no command line argument support for database configuration. Values given under the `postgres`
block are passed directly to the [pq](github.com/lib/pq) driver. Here is a rundown of all the different
values that can go in that section:
| Name | Required | Default |
| --- | --- | --- |
| dbname | yes | none |
| host | yes | none |
| port | no | 5432 |
| user | yes | none |
| pass | no | none |
| sslmode | no | "require" |
You can also pass in these top level configuration values if you would prefer
not to pass them through the command line or environment variables:
| Name | Default |
| --- | --- |
| base_dir | none |
| pkg_name | "models" |
| out_folder| "models" |
| exclude | [ ] |
**Example:**
```toml
[postgres]
dbname="dbname"
host="localhost"
port=5432
user="dbusername"
pass="dbpassword"
```
## Usage
#### Initial Generation
@ -169,7 +215,7 @@ Follow the steps below to do some basic model generation. Once we've generated
our models, we can run the compatibility tests which will exercise the entirety
of the generated code. This way we can ensure that our database is compatible
with sqlboiler. If you find there are some failing tests, please check the
[faq](#FAQ) section.
[Diagnosing Problems](#diagnosing-problems) section.
```shell
# Generate our models and exclude the migrations table
@ -180,75 +226,7 @@ go test ./models # This requires an administrator postgres user because of some
# voodoo we do to disable triggers for the generated test db
```
## How to boil your database
#### Download
```shell
go get -u -t github.com/vattle/sqlboiler
```
#### Configuration
Create a configuration file. Because the project uses [viper](github.com/spf13/viper), TOML, JSON and YAML
are all supported. Environment variables are also able to be used.
We will assume TOML for the rest of the documentation.
The configuration file is searched for in the following directories in this
order:
- `./`
- `$XDG_CONFIG_HOME/sqlboiler/`
- `$HOME/.config/sqlboiler/`
```shell
vim ./sqlboiler.toml
```
We recommend you pass in the `postgres` configuration via the configuration file rather than env vars.
There is no command line argument support for database configuration. Values given under the `postgres`
block are passed directly to the [pq](github.com/lib/pq) driver. Here is a rundown of all the different
values that can go in that section:
| Name | Required | Default |
| --- | --- | --- |
| dbname | yes | none |
| host | yes | none |
| port | no | 5432 |
| user | yes | none |
| pass | no | none |
| sslmode | no | "require" |
You can also pass in these top level configuration values if you would prefer
not to pass them through the command line or environment variables:
| Name | Default |
| --- | --- |
| base_dir | none |
| pkg_name | "models" |
| out_folder| "models" |
| exclude | [ ] |
Example:
```toml
[postgres]
dbname="dbname"
host="localhost"
port=5432
user="dbusername"
pass="dbpassword"
sslmode="require"
```
## Compatibility Tests
Once you've generated your models package, we **highly** recommend you run `go test` in your generated folder.
This should give a very clear indication of any potential database misconfiguration or schema incompatibilities.
Successful test run means you're ready to start hacking!
**Note:** If you find the tests do not pass we do not recommend using your generated package unless you know exactly why.
If you find any incompatibilities not mentioned in this readme please let us know.
---
## Diagnosing Problems
@ -257,17 +235,89 @@ The most common causes of problems and panics are:
- Forgetting to exclude tables you do not want included in your generation, like migration tables.
- Tables without a primary key. All tables require one.
- Forgetting foreign key constraints on your columns that reference other tables.
- The compatibility tests that run against your own DB schema require a superuser, ensure the user
supplied in your config has adequate privileges.
- A nil or closed database handle. Ensure your passed in `boil.Executor` is not nil.
- If you decide to use the `G` variant of functions instead, make sure you've initialized your
global database handle using `boil.SetDB()`.
- The compatibility tests that run against your own DB schema require a superuser, ensure the user
supplied in your config has adequate privileges.
For errors with other causes, it may be simple to debug yourself by looking at the generated code.
Setting `boil.DebugMode` to `true` can help with this. You can change the output using `boil.DebugWriter` (defaults to `os.Stdout`).
If you're still stuck and/or you think you've found a bug, feel free to leave an issue and we'll do our best to help you.
---
## Features & Examples
### Function Variations
### Automatic CreatedAt/UpdatedAt
If your generated SQLBoiler models package can find columns with the
names `created_at` or `updated_at` it will automatically set them
to `time.Now()` in your database, and update your object appropriately.
To disable this feature use `--no-auto-timestamps`.
**Note:** You can set the timezone for this feature by calling `boil.SetLocation()`
#### Overriding Automatic Timestamps
* **Insert**
* Timestamps for both `updated_at` and `created_at` that are zero values will be set automatically.
* To set the timestamp to null, set `Valid` to false and `Time` to a non-zero value.
This is somewhat of a work around until we can devise a better solution in a later version.
* **Update**
* The `updated_at` column will always be set to `time.Now()`. If you need to override
this value you will need to fall back to another method in the meantime: `boil.SQL()`,
overriding `updated_at` in all of your objects using a hook, or create your own wrapper.
* **Upsert**
* `created_at` will be set automatically if it is a zero value, otherwise your supplied value
will be used. To set `created_at` to `null`, set `Valid` to false and `Time` to a non-zero value.
* The `updated_at` column will always be set to `time.Now()`.
### Hooks
### Query Mod System
### Finishers
### Raw Query
### Binding
### Transactions
### Debug Logging
### Select
### Find
### Insert
### Update
updateall slice and query
### Delete
deleteall slice and query
### Upsert
### Reload
reloadall slice
### Relationships
relationships to one and to many
relationship set ops (to one: set, remove, tomany: add, set, remove)
eager loading (nested and flat)
---
## Benchmarks
---
## FAQ
### Won't compiling models for a huge database be very slow?
@ -276,4 +326,4 @@ No, because Go's toolchain - unlike traditional toolchains - makes the compiler
instead of the linker. This means that when the first `go install` is done it can take
a little bit of time because there is a lot of code that is generated. However, because of this
work balance between the compiler and linker in Go, linking to that code afterwards in the subsequent
compiles is extremely fast.
compiles is extremely fast.