{"id":19476109,"url":"https://github.com/sun1211/postgresql-docker-replication","last_synced_at":"2026-05-06T04:31:42.986Z","repository":{"id":132558516,"uuid":"507322217","full_name":"sun1211/postgresql-docker-replication","owner":"sun1211","description":"This guide explains how to set up a PostgreSQL database with Docker, configure master-slave replication, and use TypeORM for database operations in a Node.js app. It includes PostgreSQL commands, basic queries, and examples of read/write operations using TypeORM. Perfect for quickly deploying PostgreSQL with TypeORM.","archived":false,"fork":false,"pushed_at":"2025-09-19T17:34:40.000Z","size":89,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-19T19:56:08.416Z","etag":null,"topics":["database-replication","docker","postgresql","typeorm"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/sun1211.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":"2022-06-25T13:45:17.000Z","updated_at":"2025-09-19T17:34:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"f665937e-f174-4846-aceb-c81332fdb060","html_url":"https://github.com/sun1211/postgresql-docker-replication","commit_stats":null,"previous_names":["sun1211/postgresql-docker-replication"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sun1211/postgresql-docker-replication","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun1211%2Fpostgresql-docker-replication","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun1211%2Fpostgresql-docker-replication/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun1211%2Fpostgresql-docker-replication/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun1211%2Fpostgresql-docker-replication/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sun1211","download_url":"https://codeload.github.com/sun1211/postgresql-docker-replication/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun1211%2Fpostgresql-docker-replication/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32678584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["database-replication","docker","postgresql","typeorm"],"created_at":"2024-11-10T19:36:35.100Z","updated_at":"2026-05-06T04:31:42.977Z","avatar_url":"https://github.com/sun1211.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostgreSQL Master Replica\n\nThis project demonstrates a **PostgreSQL 16 primary–standby (master–replica)** setup using Docker Compose and streaming replication, with a TypeORM API for testing database operations.\n\n---\n\n## 📂 Project Structure\n\n```\n.\n├── docker-compose.yml\n├── primary/\n│   ├── data/                   # Primary database volume (ignored in git)\n│   └── init-replication.sh     # Script to configure primary for replication\n├── replica/\n│   ├── data/                   # Replica database volume (ignored in git)\n│   └── replica-entrypoint.sh   # Script to bootstrap replica via pg_basebackup\n├── src/                        # TypeORM API source code\n└── package.json                # Node.js dependencies and scripts\n```\n\n---\n\n## ⚙️ Setup\n\n### 1. Clone the repo and prepare folders\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd \u003cyour-repo\u003e\n\n# Use npm script to setup directories and permissions\nnpm run setup\n```\n\n### 2. Install dependencies\n\n```bash\nnpm install\n```\n\n### 3. Start the PostgreSQL containers\n\n```bash\n# Start both primary and replica containers\nnpm run start-postgress\n\n# Or manually:\ndocker compose up -d\n```\n\n### 4. Run database migrations\n\nAfter the containers are running, migrate the database:\n\n```bash\nnpm run migration:run\n```\n\n### 5. Start the API server\n\n```bash\nnpm start\n```\n\nThe API will be available at `http://localhost:3000`\n\n---\n\n## ▶️ Running\n\n### Quick start (all services):\n\n```bash\nnpm run setup           # Setup directories\nnpm run start-postgress # Start PostgreSQL containers\nnpm run migration:run   # Run database migrations\nnpm start              # Start API server\n```\n\n### Stop everything:\n\n```bash\ndocker compose down\n```\n\n### Clean up (removes all data):\n\n```bash\nnpm run clean\n```\n\n---\n\n## 🔌 API Testing\n\nThe TypeORM API provides endpoints for testing database operations across the master-replica setup.\n\n### Create a User\n\n```bash\ncurl -X POST http://localhost:3000/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\"\n  }'\n```\n\n**Expected Response:**\n```json\n{\n  \"id\": 1,\n  \"name\": \"John Doe\",\n  \"email\": \"john.doe@example.com\",\n  \"createdAt\": \"2024-01-20T10:30:00.000Z\"\n}\n```\n\n### Get All Users\n\n```bash\ncurl -X GET http://localhost:3000/users\n```\n\n**Expected Response:**\n```json\n[\n  {\n    \"id\": 1,\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"createdAt\": \"2024-01-20T10:30:00.000Z\"\n  }\n]\n```\n\n### Get User by ID\n\n```bash\ncurl -X GET http://localhost:3000/users/1\n```\n\n---\n\n## ✅ Verification\n\n### 1. Check replication status on **primary**\n\n```bash\ndocker exec -it pg-primary psql -U postgres -c \\\n\"SELECT pid, usename, application_name, client_addr, state, sync_state FROM pg_stat_replication;\"\n```\n\n**Expected:**\n* `state = streaming`\n* `sync_state = async` (or `sync` if configured)\n\n---\n\n### 2. Check standby mode\n\n```bash\ndocker exec -it pg-replica psql -U postgres -c \"SELECT pg_is_in_recovery();\"\n```\n\n**Expected:** `t` (true)\n\n---\n\n### 3. Check WAL receiver on replica\n\n```bash\ndocker exec -it pg-replica psql -U postgres -c \\\n\"SELECT status, conninfo, last_msg_send_time, last_msg_receipt_time FROM pg_stat_wal_receiver;\"\n```\n\n**Expected:** `status = streaming` with recent timestamps.\n\n---\n\n### 4. Check replication lag (on primary)\n\n```bash\ndocker exec -it pg-primary psql -U postgres -c \\\n\"SELECT application_name, client_addr, write_lag, flush_lag, replay_lag FROM pg_stat_replication;\"\n```\n\n---\n\n### 5. Check replay delay (on replica)\n\n```bash\ndocker exec -it pg-replica psql -U postgres -c \\\n\"SELECT now() - pg_last_xact_replay_timestamp() AS replication_delay;\"\n```\n\n---\n\n### 6. Functional test via API\n\nTest replication by creating a user via the API (writes to primary) and then checking if it appears on the replica:\n\n**Create user via API:**\n```bash\ncurl -X POST http://localhost:3000/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Test User\", \"email\": \"test@example.com\"}'\n```\n\n**Check on replica directly:**\n```bash\ndocker exec -it pg-replica psql -U postgres -c \\\n\"SELECT * FROM users ORDER BY id DESC LIMIT 1;\"\n```\n\n**Expected:** The newly created user should appear on the replica.\n\n---\n\n### 7. Database-level functional test\n\nOn **primary**:\n\n```bash\ndocker exec -it pg-primary psql -U postgres -c \\\n\"CREATE TABLE IF NOT EXISTS repl_test(id serial PRIMARY KEY, t text); \\\n INSERT INTO repl_test(t) VALUES ('hello from primary');\"\n```\n\nOn **replica**:\n\n```bash\ndocker exec -it pg-replica psql -U postgres -c \"SELECT * FROM repl_test;\"\n```\n\n**Expected:** the inserted row should appear on the replica.\n\n---\n\n## 🔄 Database Management Scripts\n\n### Generate new migration\n\n```bash\nnpm run migration:generate -- src/migrations/NewMigrationName\n```\n\n### Run migrations\n\n```bash\nnpm run migration:run\n```\n\n### Revert last migration\n\n```bash\nnpm run migration:revert\n```\n\n---\n\n## 🚀 Promote Replica (Failover)\n\nPromote the standby to a new primary:\n\n```bash\ndocker exec -it pg-replica psql -U postgres -c \"SELECT pg_promote();\"\n```\n\nAfter promotion, you'll need to update your application's database connection to point to the new primary.\n\n---\n\n## 🧹 Cleanup\n\n### Remove containers only (keep data):\n\n```bash\ndocker compose down\n```\n\n### Remove containers and data volumes:\n\n```bash\nnpm run clean\n```\n\nThis will stop containers and remove all database data from both primary and replica.\n\n---\n\n## ⚠️ Notes\n\n* This setup is for **local development/demo** only.\n* The API connects to the **primary** database for both reads and writes.\n* For production:\n  * Use **strong passwords** and restrict replication connections in `pg_hba.conf`.\n  * Consider **replication slots** to prevent WAL loss.\n  * Enable **TLS** for secure connections.\n  * Use HA tools like **Patroni**, **repmgr**, or **pgpool** for automated failover and management.\n  * Implement read/write splitting to direct reads to replica and writes to primary.\n  * Add proper error handling and connection pooling in the API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun1211%2Fpostgresql-docker-replication","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsun1211%2Fpostgresql-docker-replication","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun1211%2Fpostgresql-docker-replication/lists"}