Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/datalust/piggy
A friendly PostgreSQL script runner in the spirit of DbUp.
https://github.com/datalust/piggy
migrator postgres postgresql schema-migrations
Last synced: 1 day ago
JSON representation
A friendly PostgreSQL script runner in the spirit of DbUp.
- Host: GitHub
- URL: https://github.com/datalust/piggy
- Owner: datalust
- License: apache-2.0
- Created: 2017-07-19T02:47:03.000Z (over 7 years ago)
- Default Branch: dev
- Last Pushed: 2024-06-17T04:51:38.000Z (7 months ago)
- Last Synced: 2024-11-30T06:36:55.183Z (29 days ago)
- Topics: migrator, postgres, postgresql, schema-migrations
- Language: C#
- Homepage:
- Size: 10.9 MB
- Stars: 78
- Watchers: 10
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A friendly PostgreSQL script runner in the spirit of [DbUp](https://github.com/DbUp/DbUp).
[](https://ci.appveyor.com/project/datalust/piggy)
### What is Piggy?
Piggy is a simple command-line tool for managing schema and data changes to PostgreSQL databases. Piggy looks for `.sql` files in a directory and applies them to the database in order, using transactions and a change log table to ensure each script runs only once per database.
### Installation
Piggy is available as a .NET tool package, as standalone binaries, and as a C♯ library that can be used directly in .NET applications.
#### `dotnet tool`
Piggy is distributed as a [.NET tool package called _Datalust.Piggy.Cli_](https://nuget.org/packages/datalust.piggy.cli), which can be installed using:
```
dotnet tool install --global Datalust.Piggy.Cli
```
The executable is called `piggy`. Test that the installation was successful with:
```
piggy --version
```
#### Executable binaries
Pre-built, native, self-contained Piggy binaries are available for Windows, macOS and Linux from [the releases page](https://github.com/datalust/piggy/releases). If your platform of choice isn't listed, please [raise an issue here](https://github.com/datalust/piggy/issues) so that we can add it.
#### C# library
For development and test automation purposes, the core script runner is also packaged as a C♯ API and [published to NuGet as _Datalust.Piggy_](https://nuget.org/packages/datalust.piggy).
```csharp
// dotnet add package Datalust.Piggy
var connectionString = // Npgsql connection string
using (var connection = DatabaseConnector.Connect(connectionString))
{
UpdateSession.ApplyChangeScripts(connection, "./db", new Dictionary());
}
```
### Workflow
To manage database updates with Piggy, write SQL scripts to make changes, rather than applying changes directly.
Organize change scripts on the file system under a _script root_ directory. Name files so that they sort lexicographically in the order in which they need to be executed:
```
001-create-schema.sql
002-create-users-table.sql
003-...
```
If the scripts are arranged in subdirectories, these must be ordered by name as well:
```
v1/
001-create-schema.sql
002-create-users-table.sql
003-...
v2/
001-rename-users-table.sql
```
Piggy enumerates `.sql` files and generates names like `/v1/001-create-schema.sql` using each script's filename relative to the script root. These relative names are checked against the change log table to determine which of them need to be run.
To bring a database up to date, run `piggy up`, providing the script root, host, database name, username and password:
```
piggy up -s -h -d -u -p
```
If the database does not exist, Piggy will create it using sensible defaults. To opt out of this behavior, add the `--no-create` flag.
Over time, as your application grows, create new scripts to move the database forwards - don't edit the existing ones, since they've already been applied and will be ignored by Piggy.
Piggy can be used to update from any previous schema version to the current one: scripts that have already been run on a database are ignored, so only necessary scripts are applied.
For more detailed usage information, run `piggy help up`; to see all available commands run `piggy help`.
### Transactions
Piggy wraps each script in a transaction that also covers the change log table update. A few DDL statements can't run within a transaction in PostgreSQL - in these cases, add:
```sql
-- PIGGY NO TRANSACTION
```
as the first line of the script.
### Variable substitution
Piggy uses `$var$` syntax for replaced variables:
```sql
create table $schema$.users (name varchar(140) not null);
insert into $schema$.users (name) values ('$admin$');
```
Values are inserted using pure text substitution: no escaping or other processing is applied. If no value is supplied for a variable that appears in a script, Piggy will leave the script unchanged (undefined variables will not be replaced with the empty string).
Variables are supplied on the command-line with the `-v` flag:
```
piggy up ... -v schema=myapp -v admin=myuser
```
### Change log
The change log is stored in the target database in `piggy.changes`. The `piggy log` command is used to view applied change scripts.
### Help
Run `piggy help` to see all available commands, and `piggy help ` for detailed command help.
```
> piggy help
Usage: piggy []
Available commands are:
baseline Add scripts to the change log without running them
help Show information about available commands
log List change scripts that have been applied to a database
pending Determine which scripts will be run in an update
up Bring a database up to date
--version Print the current executable version
Type `piggy help ` for detailed help
```