{"id":50343078,"url":"https://github.com/pjiaquan/nocodb-postgres-boilerplate","last_synced_at":"2026-05-29T18:30:27.990Z","repository":{"id":345934290,"uuid":"1187911567","full_name":"pjiaquan/nocodb-postgres-boilerplate","owner":"pjiaquan","description":"Schema-first NocoDB + PostgreSQL boilerplate with automatic bootstrap","archived":false,"fork":false,"pushed_at":"2026-03-21T11:25:38.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T02:24:31.590Z","etag":null,"topics":["boilerplate","docker-compose","nocodb","postgresql","schema-first"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/pjiaquan.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T11:03:41.000Z","updated_at":"2026-03-21T11:25:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pjiaquan/nocodb-postgres-boilerplate","commit_stats":null,"previous_names":["pjiaquan/nocodb-postgres-boilerplate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pjiaquan/nocodb-postgres-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjiaquan%2Fnocodb-postgres-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjiaquan%2Fnocodb-postgres-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjiaquan%2Fnocodb-postgres-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjiaquan%2Fnocodb-postgres-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pjiaquan","download_url":"https://codeload.github.com/pjiaquan/nocodb-postgres-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjiaquan%2Fnocodb-postgres-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33666290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["boilerplate","docker-compose","nocodb","postgresql","schema-first"],"created_at":"2026-05-29T18:30:27.193Z","updated_at":"2026-05-29T18:30:27.979Z","avatar_url":"https://github.com/pjiaquan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NocoDB PostgreSQL Boilerplate\n\nSchema-first boilerplate for teams that want PostgreSQL as the source of truth and NocoDB as the UI layer, without manual NocoDB bootstrap steps.\n\nThis template gives you:\n\n- PostgreSQL + Redis + NocoDB via Docker Compose\n- SQL migrations as the only approved schema path\n- automatic base creation, PostgreSQL integration, source binding, and metadata sync\n- hard-fail startup when `.env` or required variables are missing\n- bind-mounted local data directories under `./data`\n\nIt does not generate custom NocoDB UI metadata such as forms, views, or shared links.\n\n## What Happens On Startup\n\nOn `docker compose up -d --build`, the stack automatically:\n\n1. starts PostgreSQL and Redis\n2. runs SQL migrations\n3. starts NocoDB\n4. signs in with the admin account from `.env`\n5. creates or reuses the NocoDB base\n6. creates or reuses the PostgreSQL integration\n7. binds the base source to `APP_SCHEMA`\n8. clears NocoDB metadata cache\n9. triggers metadata sync\n\nYou do not need to click `Create Base`, `Connect External Data`, or `Meta Sync`.\n\n## Use This Template\n\nRecommended flow for a new project:\n\n1. Create a new repository from this boilerplate, or copy it into a new repo.\n2. Rename the project-level settings in `.env`, especially:\n   - `COMPOSE_PROJECT_NAME`\n   - `APP_SCHEMA`\n   - `NOCODB_BASE_TITLE`\n   - `NOCODB_INTEGRATION_TITLE`\n   - `NC_PUBLIC_URL`\n3. Replace `db/migrations/0001_init_app.sql` with your real initial schema.\n4. Start the stack and confirm the example bootstrap works in your new repo.\n5. Make your first project-specific commit before adding business logic or extra services.\n\n## Quick Start\n\n1. Copy the env template.\n\n```bash\ncp .env.example .env\n```\n\n2. Change at least:\n\n- `POSTGRES_PASSWORD`\n- `REDIS_PASSWORD`\n- `NC_AUTH_JWT_SECRET`\n- `NC_ADMIN_EMAIL`\n- `NC_ADMIN_PASSWORD`\n- `NC_PUBLIC_URL`\n\n3. Start the stack.\n\n```bash\ndocker compose up -d --build\n```\n\n4. Check status.\n\n```bash\ndocker compose ps\ndocker compose logs migrate\ndocker compose logs bootstrap\n```\n\n5. Open NocoDB and sign in with `NC_ADMIN_EMAIL` and `NC_ADMIN_PASSWORD`.\n\nThe base should already exist, and the example table should already be visible.\n\nIf `bootstrap` exits early, check `docker compose logs bootstrap` first. The most common cause is that NocoDB accepted TCP connections later than Compose marked the service as started. This boilerplate now waits for a NocoDB healthcheck and keeps retrying sign-in until timeout.\n\n## What You Replace First\n\nBefore using this as a real project, replace or adjust:\n\n1. `db/migrations/0001_init_app.sql`\n2. `APP_SCHEMA` in `.env`\n3. `NOCODB_BASE_TITLE`\n4. `NOCODB_INTEGRATION_TITLE`\n5. `NC_PUBLIC_URL`\n6. any example tables or views you do not want\n\n## Repository layout\n\n- `.env.example`: required environment variables\n- `docker-compose.yml`: stack definition\n- `bootstrap/Dockerfile`: bootstrap image\n- `scripts/bootstrap_nocodb.sh`: NocoDB bootstrap flow\n- `scripts/update_schema_snapshot.sh`: refresh schema snapshot\n- `scripts/check_schema_drift.sh`: compare live schema with snapshot\n- `db/migrations`: SQL migrations\n- `data/postgres`: PostgreSQL data\n- `data/redis`: Redis data\n- `data/nocodb`: NocoDB local data\n\nPostgreSQL uses `PGDATA=/var/lib/postgresql/data/pgdata`, so the bind-mounted `data/postgres` root can safely contain mount-point metadata or a tracked `.gitkeep`. If you previously saw `initdb: error: directory \"/var/lib/postgresql/data\" exists but is not empty`, clear `data/postgres` and start again.\n\n## Current defaults\n\nThe boilerplate ships with:\n\n- `APP_SCHEMA=app`\n- base title `App Data`\n- integration title `App PostgreSQL`\n- one example table: `example_records`\n- one example view: `v_example_record_counts`\n\nThe example migration is intentionally small. Replace it with your real domain schema.\n\n## Why this boilerplate uses a dedicated schema\n\nNocoDB stores its own metadata tables in PostgreSQL. If your business tables live in the same scanned schema, NocoDB can import its own `nc_*` tables during metadata sync.\n\nThis boilerplate avoids that by keeping business tables in a dedicated schema, defaulting to `app`.\n\n## Why the bootstrap script touches NocoDB metadata tables\n\nThe current bootstrap flow uses a mix of:\n\n- NocoDB API calls for auth, workspace lookup, base creation, and integration creation\n- direct PostgreSQL updates to `nc_integrations_v2` and `nc_sources_v2` for deterministic source rebinding\n\nThat choice is deliberate. It avoids the manual UI flow and worked more reliably than relying on the source-binding API flow alone.\n\nIf a future NocoDB release changes these metadata tables, the bootstrap script may need adjustment.\n\n## Hard-fail behavior\n\nIf `.env` is missing, or required variables are missing, `docker compose` fails immediately with a clear interpolation error such as:\n\n```text\nrequired variable DATABASE_URL is missing a value\n```\n\nIt does not continue with blank values.\n\n## Common commands\n\nStart:\n\n```bash\ndocker compose up -d --build\n```\n\nStop:\n\n```bash\ndocker compose down\n```\n\nRe-run migrations:\n\n```bash\ndocker compose run --rm migrate --wait --wait-timeout 120s --migrations-dir /db/migrations --no-dump-schema up\n```\n\nRe-run bootstrap:\n\n```bash\ndocker compose run --rm bootstrap\n```\n\nUpdate schema snapshot:\n\n```bash\nbash scripts/update_schema_snapshot.sh\n```\n\nCheck schema drift:\n\n```bash\nbash scripts/check_schema_drift.sh\n```\n\n## Reset a disposable local environment\n\nThis boilerplate uses bind mounts under `./data`.\n\nTo reset local state:\n\n1. stop the stack\n2. delete `data/postgres`, `data/redis`, and `data/nocodb`\n3. run `docker compose up -d --build` again\n\n## Suggested next step\n\nAfter cloning this boilerplate for a real project, make your first commit with:\n\n- renamed base title\n- renamed schema if needed\n- replaced initial migrations\n- updated README\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjiaquan%2Fnocodb-postgres-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpjiaquan%2Fnocodb-postgres-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjiaquan%2Fnocodb-postgres-boilerplate/lists"}