|
1 | 1 | # setup-postgres |
2 | 2 |
|
3 | | -Fast (really fast), cross-platform, unconfined setup for Postgres in GitHub Actions. |
4 | | - |
5 | | -Works for all OSs and architectures supported by GitHub Actions! |
| 3 | +Lightning-fast Postgres setup for GitHub Actions that just works. Cross-platform, unconfined, and ready for all environments GitHub Actions supports. |
6 | 4 |
|
7 | 5 | <img src="bar.png" alt="Install Times" width="200"/> |
8 | 6 |
|
9 | 7 | # Features |
10 | 8 |
|
11 | | -- [x] Binaries installed, in PATH, fast! |
12 | | -- [x] Starts postgres in fast-mode*, fast! |
13 | | -- [x] Environment variables setup for use in steps, fast! |
14 | | - |
15 | | -No Docker, no non-portable package managers. Just the binaries you need, |
16 | | -installed and ready to do, fast! |
| 9 | +- **Pure Speed**: Binary-based installation that gets you running in seconds |
| 10 | +- **Zero Friction**: No Docker, no package managers - just what you need |
| 11 | +- **Universal**: Works across every OS and architecture GitHub Actions supports |
| 12 | +- **No yaml hassle**: Environment variables pre-configured for immediate use in following steps, without intermediate yaml |
17 | 13 |
|
18 | | -# Usage |
| 14 | +# Get Started |
19 | 15 |
|
20 | 16 | ```yaml |
21 | 17 | steps: |
22 | | - # ... |
23 | 18 | - uses: bmizerany/setup-postgres@v3 |
24 | | - |
25 | | - # Run your migrations, tests, etc. |
| 19 | + |
| 20 | + # Your workflow runs here |
26 | 21 | - run: psql 'SELECT 1' |
27 | 22 | - run: go test ./... |
28 | 23 | - run: bun test |
29 | | - # ... |
30 | 24 | ``` |
31 | 25 |
|
32 | | -That's it! |
33 | | - |
34 | | -## Supported OSs and Architectures |
| 26 | +That's all it takes. No configuration needed. |
35 | 27 |
|
36 | | -This action supports all OSs and architectures that GitHub actions supports; at |
37 | | -the time of writing. |
| 28 | +# Core Features |
38 | 29 |
|
39 | | -## Supported Versions |
| 30 | +## Version Support |
| 31 | +Install any Postgres version using standard semantic versioning (`X.Y.Z`). We pull directly from the embedded-postgres project's verified binaries. |
40 | 32 |
|
41 | | -A version may be specified in the form of `X.Y.Z` where `X`, `Y`, and `Z` are |
42 | | -integers. The version must be a valid version of postgres that is available |
43 | | -from the [embedded postgres project](https://github.com/zonkyio/embedded-postgres). |
| 33 | +Browse available versions [here](https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-linux-amd64/). |
44 | 34 |
|
45 | | -A list of supported versions can be found [here](https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-linux-amd64/). |
46 | | - |
47 | | -## Environment variables |
48 | | - |
49 | | -The action will set the following environment variables for subsequent steps: |
50 | | - |
51 | | -| Name | Description | |
52 | | -| --- | --- | |
53 | | -| `PGHOST` | The host to connect to (default: `localhost`) | |
54 | | -| `PGPORT` | The port to connect to (default: `5432`) | |
55 | | -| `PGUSER` | The user to connect as (default: `postgres`) | |
56 | | -| `PGPASSWORD` | The password to connect with (default: `postgres`) | |
57 | | -| `PGDATABASE` | The database to connect to (default: `postgres`) | |
58 | | -| `PGDATA` | The data directory for the running postgres instance | |
59 | | -| `DATABASE_URL` | The DSN that can be used to connect to the database | |
60 | | - |
61 | | -> NOTE: `DATABASE_URL` is in the DSN form (e.g. `dbname=postgres user=postgres |
62 | | -> ...`) which is accepted my most Postgres clients, drivers, ORMs, etc. It |
63 | | -> was chosen over an actual URL because it is more flexible, and easier to |
64 | | -> override settings by simply appending new settings to the string. |
65 | | -> |
66 | | -> Users that want a URL can build one like: `postgres://$PGUSER:$PGPASSWORD@$PGHOST:$PGPORT/$PGDATABASE` |
| 35 | +## Environment Configuration |
| 36 | +Your workflow steps automatically get these environment variables: |
67 | 37 |
|
| 38 | +| Variable | Purpose | Default | |
| 39 | +| --- | --- | --- | |
| 40 | +| `PGHOST` | Connection host | `localhost` | |
| 41 | +| `PGPORT` | Connection port | `5432` | |
| 42 | +| `PGUSER` | Username | `postgres` | |
| 43 | +| `PGPASSWORD` | Password | `postgres` | |
| 44 | +| `PGDATABASE` | Target database | `postgres` | |
| 45 | +| `PGDATA` | Data directory | *runtime path* | |
| 46 | +| `DATABASE_URL` | Connection string | DSN format | |
| 47 | + |
| 48 | +The `DATABASE_URL` uses DSN format for maximum flexibility. For URL format, construct it like this: |
| 49 | +``` |
| 50 | +postgres://$PGUSER:$PGPASSWORD@$PGHOST:$PGPORT/$PGDATABASE |
| 51 | +``` |
68 | 52 |
|
69 | | -## Inputs |
| 53 | +## Configuration Options |
70 | 54 |
|
71 | | -| Name | Description | Default | |
| 55 | +### Inputs |
| 56 | +| Name | Purpose | Default | |
72 | 57 | | --- | --- | --- | |
73 | | -| `version` | The version of postgres to install | `17.2.0` | |
| 58 | +| `version` | Postgres version | `17.2.0` | |
74 | 59 |
|
75 | | -## Outputs |
| 60 | +### Outputs |
| 61 | +For advanced workflow configuration: |
76 | 62 |
|
77 | | -Outputs are provided for use in configuring other steps in a workflow. It is |
78 | | -assumed most users will not need them for normal use, and instead can rely on |
79 | | -the environment variables set by this action. |
80 | | - |
81 | | -| Name | Description | |
| 63 | +| Name | Purpose | |
82 | 64 | | --- | --- | |
83 | | -| `dsn` | The DSN that can be used to connect to the database | |
84 | | -| `data` | The data directory for the running postgres instance | |
85 | | - |
86 | | -## Fast-mode |
| 65 | +| `dsn` | Database connection string | |
| 66 | +| `data` | Postgres data directory | |
87 | 67 |
|
88 | | -This action runs postgres in "fast-mode" which is a mode that disables `fsync` |
89 | | -and `full_page_writes`. This is not recommended for production use, but is great |
90 | | -for CI/CD environments where you want to get up and running quickly, and for |
91 | | -tests to run lightning fast. |
| 68 | +# Performance Notes |
92 | 69 |
|
93 | | -# Credits |
| 70 | +This action runs Postgres in fast mode, disabling `fsync` and `full_page_writes`. Perfect for CI/CD, not recommended for production. Your tests will fly. |
94 | 71 |
|
95 | | -This is possible thanks to the [embedded postgres project](https://github.com/zonkyio/embedded-postgres) |
96 | | -which provides pre-built binaries for many versions of postgres. Please |
97 | | -consider supporting them if you find this action useful. |
| 72 | +# Acknowledgments |
98 | 73 |
|
99 | | -This is obviously most possible because of the hard work of the postgres |
100 | | -community. Thank you! |
| 74 | +Built on the shoulders of giants: |
| 75 | +- [embedded postgres project](https://github.com/zonkyio/embedded-postgres) for their essential binary distributions |
| 76 | +- The Postgres community for their foundational work |
101 | 77 |
|
102 | 78 | # Contributing |
103 | 79 |
|
104 | | -Please open an issue for any feature requests, bugs, or questions. Large PRs |
105 | | -(e.g. new features) should be discussed in an issue first. Small PRs for bug |
106 | | -fixes, typos, etc are welcome without an issue. |
| 80 | +We value collaboration: |
| 81 | +- Open issues for features and bugs |
| 82 | +- Discuss major changes before PR |
| 83 | +- Small fixes welcome anytime |
| 84 | +- Be kind, or else |
| 85 | + |
| 86 | +--- |
107 | 87 |
|
108 | | -Also, be nice, or else. |
| 88 | +*Note: This project thrives because of community support. Consider supporting the embedded postgres project if you find value here.* |
0 commit comments