pgzod

pgzod

Transform PostgreSQL schemas into Zod validators and types
Explore the docs »
Report Bug · Request Feature

Table of Contents

• 1. About The Project
  • 1.1. Built With
• 2. Getting Started
• 3. Usage
• 4. Roadmap
• 5. Contributing
• 6. License
• 7. Contact

1. About The Project

Keeping Typescript types in sync with your PostgreSQL database schemas is very useful but challenging. With PGZod that you can maintain all your tables in sync with Typescript through "Zod". Zod is, in their own words:

a TypeScript-first schema declaration and validation library. You can use a Zod schema for validation or as a normal type.

It works great when you couple it with a PostgreSQL client like slonik.

(back to top)

1.1. Built With

• Slonik
• Typescript
• Yargs
• Zod

(back to top)

2. Getting Started

The best way to run PGZod is by installing it globally or using it through npx.

• npm

  npm install pgzod -g

• yarn

  yarn global add pgzod

If you want to use npx, you don't have to install PGZod run:

# Shows the command help.
npx pgzod --help

(back to top)

3. Usage

You can use PGZod from the command line. It needs the credentials and the address of the live database from where to read the schema. You can provide this information through command options or environment variables. All the variables from PostgreSQL are supported.

Your database credentials could be stored on a local .env file, or even better, on a secret manager. You then load the credentials to your current session and run the PGZod command.

For example, you could build the following .env file:

PGHOST=some.postgresql.host
PGPORT=12345
PGDATABASE=app
PGSSLMODE=require
PGUSER=postgres
PGPASSWORD=yourpassword!

Load the .env variables, and override others through command options.

env $(xargs < .env) pgzod --pghost 127.0.0.1 --pgport 5432 --schema public

PGZod will not look for tables on your whole database just a single schema. You can indicate your database schema through the--schema option. If you don't provide it, PGZod runs against the public schemas.

For more examples, please refer to the Documentation

Strategies

PGZod offers the concept of strategies to define how it should create the Zod validator files. Here is the current list of strategies exposed:

Value	Description
write	Creates Zod validators considering only writes to the table. Columns that have default values will be marked as optional.
readwrite	Creates Zod validators for both read and write actions. PGZod will create two validators for each table with the Read and Write suffix to differentiate both actions. This is probably the strategy you want to work with.

(back to top)

4. Roadmap

• Find a better solution to deal with dates, and currently, we treat them as strings.
• Add support for more types.
• Allow the user to override the current type mappings.
• Add tests.

See the open issues for a complete list of proposed features (and known issues).

(back to top)

5. Contributing

Your contributions make the open-source community a fantastic place to learn, inspire, and create.

To suggest how to improve this project, please fork the repo and create a pull request.

You can also create an issue with the tag "enhancement."

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

6. License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

7. Contact

Your Name - @owncoral - [e-mail]

Project Link: https://github.com/owncoral/pgzod

(back to top)