From 916f9de45f78bf84d283a66127375dafeddb9bb2 Mon Sep 17 00:00:00 2001 From: Brent Schroeter Date: Tue, 18 Nov 2025 20:38:01 -0800 Subject: [PATCH] add basic development readme docs --- README.md | 48 +++++++++++++++------ dev-services/run-pg-with-apple-container.sh | 2 +- mise.toml | 5 ++- 3 files changed, 41 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 1102bde..ea24912 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,21 @@ A friendly, collaborative PostgreSQL derivative for nerds of all stripes. ![Screenshot of multi-cursor editing, as well as a dropdown menu with a highlighted option labeled "PostgreSQL credentials"](./docs/screenshot_multi_cursor.png) -## LLM Code Policy +# Development Quickstart + +The Phonograph repository comes with a [mise-en-place](https://mise.jdx.dev/) +configuration to automatically manage the development environment: + +- `mise install` installs language runtimes and tooling. +- `mise run build-css && mise run build-svelte` builds browser assets. +- `mise run docker-services` runs a Postgres container for local development. +- `mise run server` compiles and runs the server with the dev profile. + +## Configuration + +Refer to [the .env.example file](./.env.example) for configuration options. + +# LLM Code Policy Large language model code generation is permitted sparingly in very limited cases, for example for completing clearly defined transformations which span @@ -30,7 +44,7 @@ Examples of LLM-assisted changes in practice: - Replacing SVG icons with similar webfont icons from a different icon pack. (Revision `ztrnxzqv` (Git `a8dd49f7`)) -## The Phonograph Authorization Model +# The Phonograph Authorization Model Postgres provides a sophisticated role based access control (RBAC) system, which Phonograph leverages to apply permissions consistently across the web UI and @@ -50,9 +64,9 @@ creation and ownership is restricted to the "root" Phonograph role, which acts on the behalf of the user in order to facilitate schema updates via the web interface. -### Permissions Granted via User Roles +## Permissions Granted via User Roles -#### Accessing workspace databases +### Accessing workspace databases `GRANT CONNECT ON TO ;` @@ -74,14 +88,14 @@ that they might. In cases where the root Postgres user is fetching potentially sensitive data on behalf of a user, the user's actual ability to connect to the database should always be confirmed. -#### Accessing the `phono` schema +### Accessing the `phono` schema `GRANT USAGE ON TO ;` This permission is granted when initially creating the workspace, as well as when accepting an invitation to a table. -### Creating, updating, and deleting columns +## Creating, updating, and deleting columns `GRANT TO ;` @@ -92,7 +106,7 @@ permissions. **This permission is only used via the web UI and must not be granted to service credentials, lest users alter table structure in unsupported ways.** -#### Reading table data +### Reading table data `GRANT SELECT ON
TO ;` @@ -102,7 +116,7 @@ accepting an invitation to the table. Phonograph uses `SELECT` permissions to infer whether a table should be accessible to a user via the web UI. -#### Inserting rows +### Inserting rows `GRANT INSERT () ON
TO ;` @@ -115,7 +129,7 @@ permissions. These permissions must be updated for each relevant user role whenever a column is added; this is simplified by maintaining a single "writer" role per table. -#### Updating rows +### Updating rows `GRANT UPDATE () ON
TO ;` @@ -128,11 +142,11 @@ permissions. These permissions must be updated for each relevant user role whenever a column is added; this is simplified by maintaining a single "writer" role per table. -### Actions Facilitated by Root +## Actions Facilitated by Root - Creating tables -### Service Credentials +## Service Credentials Direct user PostgreSQL connections are performed using secondary `LOGIN` roles created by the user's primary workspace role (where the primary workspace role @@ -146,7 +160,17 @@ Service credential role names have the format `svc_{user_id}_{8 chars (4 bytes) of random hex}`. With the user ID consuming 32 characters, this balances name length with an ample space for possible names. -## Footnotes +# Copyright and License + +All original source code in this repository is copyright (C) 2025 Second System +Technologies LLC and distributed under the terms in +[the "LICENSE" file](./LICENSE). Certain third-party assets within +[the "static" directory](./static) may be governed by different licenses, for +example the Open Font License or MIT License, as stated by their original +authors. Copies of each relevant license have been included alongside these +files as needed. + +# Footnotes [^1]: Barring historical pedantry, "Postgres" and "PostgreSQL" are essentially diff --git a/dev-services/run-pg-with-apple-container.sh b/dev-services/run-pg-with-apple-container.sh index 4b1e897..18491f2 100644 --- a/dev-services/run-pg-with-apple-container.sh +++ b/dev-services/run-pg-with-apple-container.sh @@ -13,6 +13,6 @@ container run --name phono-pg \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=guest \ -e PGDATA=/var/lib/postgresql/18/docker/pgdata \ - -v "$(dirname "$0")/dev-services/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:ro" \ + -v "$(abspath $(dirname "$0"))/dev-services/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:ro" \ -v phono-pg:/var/lib/postgresql/18/docker \ postgres:18 diff --git a/mise.toml b/mise.toml index 1461876..03ed4b0 100644 --- a/mise.toml +++ b/mise.toml @@ -1,6 +1,5 @@ [tools] deno = "latest" -jujutsu = "latest" rebar = "latest" rust = { version = "nightly", components = "rust-analyzer,clippy,rustc-codegen-cranelift-preview" } watchexec = "latest" @@ -24,6 +23,10 @@ sources = ["**/*.svelte.ts", "**/*.svelte"] run = "sass sass/:css_dist/" sources = ["**/*.scss"] +[tasks.docker-services] +dir = "./dev-services" +run = "docker compose up" + [tasks.pg-container] run = "sh ./dev-services/run-pg-with-apple-container.sh"