{"id":19788649,"url":"https://github.com/jaredramirez/db_sync","last_synced_at":"2026-05-15T13:04:55.703Z","repository":{"id":190017978,"uuid":"681777709","full_name":"jaredramirez/db_sync","owner":"jaredramirez","description":"Define DB functions and RLS policies declaratively \u0026 sync them to your databse","archived":false,"fork":false,"pushed_at":"2024-04-12T21:51:41.000Z","size":26,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-11T03:52:22.883Z","etag":null,"topics":["declarative","postgres-functions","postgresql","row-level-security"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaredramirez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-22T18:29:11.000Z","updated_at":"2023-08-22T20:33:01.000Z","dependencies_parsed_at":"2024-11-12T06:39:27.307Z","dependency_job_id":null,"html_url":"https://github.com/jaredramirez/db_sync","commit_stats":null,"previous_names":["replenysh/db_sync"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredramirez%2Fdb_sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredramirez%2Fdb_sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredramirez%2Fdb_sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredramirez%2Fdb_sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaredramirez","download_url":"https://codeload.github.com/jaredramirez/db_sync/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241125057,"owners_count":19913839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["declarative","postgres-functions","postgresql","row-level-security"],"created_at":"2024-11-12T06:28:13.207Z","updated_at":"2025-10-10T02:02:52.232Z","avatar_url":"https://github.com/jaredramirez.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DB Sync\n\nThis is a tool used to sync Postgres [functions](https://www.postgresql.org/docs/15/sql-createfunction.html) and [row level security (RLS) policies](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) to a database based on definitions in a file tree.\nIt is valuable to manage these entities in a declarative way and there are numerous benefits, such as:\n\n1. Not needing to copy/paste an entire function/policy to make a small change\n2. See how a function changes over time with version control\n3. Easily see what new changes are introduced in PR review\n\nHowever, there are some limitations to `db_sync`, so please read this document carefully to understand the semantics.\n\n## Install \u0026 use\n\n`db_sync` can be installed as a nix flake. [Check it out on FlakesHub](https://flakehub.com/flake/jaredramirez/db_sync)\n\nHere's output of running `db_sync --help`:\n\n```\nProgram to sync function and RLS defintions defined declaratively to a database\n\nUsage: db_sync [OPTIONS] \u003cDB_URL\u003e\n\nArguments:\n  \u003cDB_URL\u003e\n\nOptions:\n      --config-path \u003cCONFIG_PATH\u003e  [default: ./db_sync.toml]\n  -h, --help                       Print help\n  -V, --version                    Print version\n```\n\n`db_sync` only supports PostgresQL.\n\n## Overview\n\n`db_sync` takes a directory structure and syncs its definitions to a database. Given a file tree like:\n\n```\nfunctions/\n├── schema_a\n│   ├── types.sql\n│   └── function_1.sql\n└── schema_b\n    └── function_2.sql\n\nrls_policies/\n├── schema_c\n│   └── table_1.sql\n└── schema_d\n    └── table_2.sql\n```\n\nAnd a config file like:\n```toml\n[functions]\ndir = './functions'\nschemas = ['a', 'b']\n\n[rls_policies]\ndir = './rls_policies'\nschemas = ['c', 'd']\n```\n\nRunning `db_sync` will, in order:\n\n1. Drop all RLS policies for all tables in schemas `c`, and `d`\n2. Drop all functions and types in  schemas `a`, and `b` (will `DROP ... CASCADE` these functions/types)\n3. Run all files named `types.sql` in `functions/`\n4. Run all other files in `functions/`\n5. Run all files `rls_policies/`\n\nAll steps are run in the same postgres transaction, so if anything fails all changes are rolledback and the database is untouched.\n\n**Be really careful about what schemas use with `db_sync`** as it will drop all RLS policies in `rls_policies.schemas` and **`DROP CASCADE` all functions and types `functions.schemas`.** I recommend using a dedicated `functions` schema that's created specifically for this tool, that way `db_sync` doesn't accidentally drop something you didn't intend.\n\n### Config\n\n`db_sync` needs a config file. This config specifies the directories to use for functions \u0026 RLS policies.\nThis config  specifies the schemas to work with for both functions and policies as well as the directories to use.\n\nSpecifiying the schemas is an important detail!\nIf you tried to define `CREATE FUNCTION schema_d.new_function` in the file `functions/` dir\nyou'd get an error because `schema_d` isn't in `config.functions.schemas`. \n\n#### Shared types via `types.sql`\n\nYou can define files called `types.sql` in your `functions/` directory. These will run before the rest of the files, so it's a great place to  create shared types that the multiple functions use.\n\n\u003e Other than the `types.sql` files, there is no gaurenteed of order the rest of the functions files will be run. If you have multiple `types.sql` files in different directories, the order that the `types` files will be run in is also not gaurenteed. However, all `*/types.sql` files will be run before any function defintion file.\n\n#### Functions bodies\n\nBefore the functions are run, we the command `SET check_function_bodies = FALSE;`. This disables the validation of bodies of functions, allowing you to reference other functions in other files without us having to do tons of cyclical dependency work. However, this means that some errors will not be caught until the functions are run. So always test you code! And write [pgtap](https://pgtap.org/) tests too!\n\n### File structure\n\nBeyond the root directory, the way the files are organizaed don't actually matter! You could have a file tree like:\n```\nfunctions/\n├── schema_a_function_1.sql\n└── schema_b_function_2.sql\n```\n\nSo long as the files only use the schemas defined in `config.functions.schemas`, `db_sync` will work.\n\nThat said, we recommend using the 1st filetree structure mentioned in this document.\n\n### Statements in the files\n\nAll statements across all files should only be `CREATE` statements, because we drop all existing functions/types/policies before running the definitions. \n\nIn `functions/`, only the following statements are allow:\n- `CREATE FUNCTION`\n- `CREATE TYPE`\n- `CREATE DOMAIN`\n- `CREATE ENUM`\n- `CREATE RANGE`\n\nIn `rls_policies/`, only the following statements are allow:\n- `CREATE POLICY`\n\n`db_sync` will error if there is an unallowed statement. \n\n## Roadmap\n\n- Add `--dry-run` flag?\n- ???\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredramirez%2Fdb_sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredramirez%2Fdb_sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredramirez%2Fdb_sync/lists"}