{"id":18029729,"url":"https://github.com/funbringer/norsu","last_synced_at":"2025-03-27T03:31:12.137Z","repository":{"id":57446721,"uuid":"134265011","full_name":"funbringer/norsu","owner":"funbringer","description":"PostgreSQL builds manager","archived":false,"fork":false,"pushed_at":"2021-06-25T22:22:08.000Z","size":129,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-06T02:51:37.050Z","etag":null,"topics":["branch","git","install","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbringer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-21T12:16:46.000Z","updated_at":"2022-04-12T14:29:47.000Z","dependencies_parsed_at":"2022-09-02T22:11:56.482Z","dependency_job_id":null,"html_url":"https://github.com/funbringer/norsu","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbringer%2Fnorsu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbringer%2Fnorsu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbringer%2Fnorsu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbringer%2Fnorsu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbringer","download_url":"https://codeload.github.com/funbringer/norsu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245040196,"owners_count":20551301,"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":["branch","git","install","postgresql"],"created_at":"2024-10-30T09:10:51.389Z","updated_at":"2025-03-27T03:31:11.827Z","avatar_url":"https://github.com/funbringer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/funbringer/norsu.svg?branch=master)](https://travis-ci.org/funbringer/norsu)\n[![PyPI version](https://badge.fury.io/py/norsu.svg)](https://badge.fury.io/py/norsu)\n\n## Norsu -- PostgreSQL builds manager\n\n### Introduction\n\nNorsu (finnish for *elephant*) is meant to be a tool for quickly installing\nand updating custom PostgreSQL builds, as well as testing your extensions\nagainst them.\n\nThis might be useful if you're an extension developer and you aim to support\nseveral major PostgreSQL releases. Over time, running regression test suites\nagainst a growing number of releases might become a cumbersome task, hence a\nneed for an automation tool.\n\nCurrently, Norsu can:\n\n* install \u0026 remove PostgreSQL release- and dev- branches and keep them up-to-date;\n* show various properties of builds (`configure` flags, commit hash, version etc);\n* search for branches across multiple git repos (specified in a [config file](#config));\n* install and test PostgreSQL extensions using regression test suites;\n\n### Setup\n\n\u003e NOTE: Python 3.3+ is required.\n\nTo install a stable release, just run the following in your favorite shell:\n\n```bash\npip install --user norsu\n```\n\nAlso, make sure that [python's user base](https://pip.readthedocs.io/en/latest/user_guide/#user-installs) is in `$PATH`:\n\n```bash\n# add this to .bashrc (or .zshrc, whatever)\nexport PATH=$PATH:$(python -c \"import site; print(site.getuserbase())\")/bin\n```\n\nand you're good to go!\n\n\nTo install a dev version, clone this repo and run:\n\n```bash\npip install --user -U .\n```\n\n### Config\n\nThe config file is located at `$NORSU_PATH/.norsu.toml` (by default, `$NORSU_PATH` is `$HOME/pg`).\n\n### Usage\n\nIn general,\n\n* If a command accepts `[target]...`, it will default to all available builds if no target is specified;\n* An interrupted command will try to continue where it left off next time;\n* Time-consuming commands print steps they're taking to achieve goals;\n\nTarget is a build's name, which is also used as install directory name: each build is installed to `$NORSU_PATH/target`.\nHere's a rule that describes possible targets:\n\n**`[^]target[:search]`**\n\n* By default, target's name is used both as install dir name and branch search string, but you can separate them using `:`;\n* Target might be positive (e.g. `master`, `9.6.5`, `10`) or negative (i.e. exclude some build, e.g. `^master`);\n* Search strings may be versions (e.g. `10`, `9.6.8`, `9.5`) or (parts of) branch names (e.g. `master`, `REL_10`);\n\nHere's a non-exhaustive list of available commands:\n\n#### `norsu install [target]... [cmd_option]...`\n\nKnown `cmd_options`:\n\n* `--extension` -- [contribs (in-tree extensions)](https://www.postgresql.org/docs/current/static/contrib.html) to be installed (e.g. `--extension pg_stat_statements auto_explain`);\n* `--configure` -- [`configure` options](https://www.postgresql.org/docs/current/static/install-procedure.html) to be applied before building process takes place;\n* `--no-update` -- do not pull \u0026 install updates (e.g. just install missing extensions, see `--extension`);\n\nFor each `target`:\n\n* if **not yet installed**, find a list of **matching** branches in known git repos (specified in a [config file](#config)),\nselect the most relevant one, configure and install it to `$NORSU_PATH/target`.\n\n* if **already installed**, check the branch for updates (new commits), then rebuild and/or reinstall if necessary.\n\nExample:\n\n```bash\n# install some releases\n$ norsu install 9.5 9.6 10\n\nSelected instance: 9.5\n        =\u003e No work dir, choosing repo \u0026 branch\n        =\u003e Selected repo git://git.postgresql.org/git/postgresql.git\n        =\u003e Selected branch REL9_5_STABLE\n        ...\n```\n\n#### `norsu search [target]...`\n\nFor each `target`, print a list of matching branches to be used by the `install` command.\nCurrently, a branch matches if `target` occurs in its name (is a substring).\n\nBranches are sorted by decreasing priority:\n* if `target` is version, branches are sorted by \"freshness\" (the most fresh release wins);\n* otherwise, branches are sorted by similarty (the most similar name wins);\n\nExample:\n\n```bash\n$ norsu search 10\n\nSearch query: 10\n         REL_10_STABLE\n         REL_10_4\n         REL_10_3\n         REL_10_2\n         REL_10_1\n         REL_10_0\n         REL_10_RC1\n         ...\n```\n\n#### `norsu pull [target]...`\n\nFor each `target`, pull new commits from a git repo (but don't re-build anything).\nThis command prints the amount of new commits available and updates info shown by the `status` command.\n\n#### `norsu status [target]...`\n\nPrint some info about each `target`, for instance:\n\n```bash\n$ norsu status master\n\nSelected instance: master\nStatus:        Installed (out of date)\nMain dir:      $HOME/pg/master\nWork dir:      $HOME/pg/.norsu/master\nBranch:        master\nVersion:       PostgreSQL 11beta1\nCommit:        6a75b58065c8da69a259657fc40d18e76157f265\nCONFIGURE:     ['CFLAGS=-g3', '--enable-cassert']\n```\n\n#### `norsu remove [target]...`\n\nRemove `targets` (main dirs) and their cached git repos (work dirs).\n\n#### `norsu pgxs [target]... [cmd_option]... [-- [make_option]...]`\n\nWhere:\n\n* `target` -- run `make ...` against the specified builds\n* `cmd_option` -- additional options for this command, e.g. `--run-pg`\n* `make_option` -- options to be passed to `make`, e.g. `clean install -j5`\n\nKnown `cmd_options`:\n\n* `-R`, `--run-pg` -- start a temp instance of PostgreSQL for the duration of the command\n\n\u003e NOTE: this command should be executed in extension's directory\n\nFor each `target`, execute `make USE_PGXS=1 PG_CONFIG=path/to/pg_config ...` in extension's directory.\n\nExamples:\n\n```bash\n# install to all builds\nnorsu pgxs\n\n# install to everything but master (options following '--' are passed to make)\nnorsu pgxs ^master -- clean install -j5\n\n# run regression tests against 9.6.9\nnorsu pgxs 9.6.9 -R -- installcheck\n\n# check using clang-analyzer for builds 9.6 and 10\nscan-build norsu pgxs 9.5 10 -- clean all\n```\n\n#### `norsu run target [cmd_option]...`\n\nKnown `cmd_options`:\n\n* `--pgxs` -- use PG config files provided by extension, as in the `pgxs` command\n* `--psql` -- run `psql` connected to a default DB after PostgreSQL has started\n* `--port` -- bind to a port provided by user (random by default)\n* `--config` -- pass a set of custom config files to a PG cluster\n* `--restore` -- restore DB from a file before node startup\n* `--dump` -- save DB dump to a file before node shutdown\n\nCreate and run a temporary instance (DB) of PostgreSQL using build named `target`.\nThe instance will be up \u0026 running until the command is interrupted (e.g. with `SIGINT`).\n\nExamples:\n\n```bash\n$ norsu run 10 --psql\n\nStarting temporary PostgreSQL instance...\n\npsql (10.4)\nType \"help\" for help.\n\npostgres=#\n```\n\n```bash\n$ norsu run master --psql --{dump,restore}=/tmp/dump.sql\nStarting temporary PostgreSQL instance...\n\ndir: /tmp/tgsn_f7c_3dh4\nport: 10451\n\nRestored from /tmp/dump.sql\n\npsql (13devel)\nType \"help\" for help.\n\npostgres[port=10451]=# create table test (val int);\nCREATE TABLE\npostgres[port=10451]=# \\q\n\nDump has been saved to /tmp/dump.sql\n\n$ cat /tmp/dump.sql\n# ... skipped\n--\n-- Name: test; Type: TABLE; Schema: public; Owner: dmitry\n--\n\nCREATE TABLE public.test (\n    val integer\n);\n```\n\n#### `norsu path [target]...`\n\nPrint paths to install dirs (main dirs) of `targets`.\n\n#### `norsu purge [target]...`\n\nFor each `target`, remove orphaned git repos (work dirs).\n\n\n### Miscellaneous\n\nDon't hesitate to open new issues and express your ideas!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbringer%2Fnorsu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbringer%2Fnorsu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbringer%2Fnorsu/lists"}