Neon Postgres Operations Guide
Travis L. Guckert
LeMay Publishing
TECHNICAL
Neon Postgres Operations Guide
Database Administration18,134 words185 chapters
Published by LeMay Publishing. 18,134 words across 185 chapters.
About This Publication
Technical manual for serverless Postgres operations, branching strategies, and production database management.
Published by LeMay Publishing, a division of LeMay. Massachusetts.
ISBN: 979-8-0000-5121-4
Chapters
1NEON POSTGRES OPERATIONS GUIDE
2Serverless Postgres Operations, Branching Strategies, and Production Database Management
3ABOUT THIS MANUAL
4TABLE OF CONTENTS
5CHAPTER 1
6Architecture of Neon — The Separation of Storage and Compute
71.1 Traditional PostgreSQL Architecture in Brief
81.2 The Neon Architecture
91.3 The Implications for Operations
101.4 The Neon-Modified PostgreSQL Build
111.5 Regional Deployment and Network Topology
121.6 Comparison with Other Architectures
131.7 Mental Model for Operations
14CHAPTER 2
15Projects, Branches, and the Neon Object Hierarchy
162.1 Organizations and Accounts
172.2 Projects
182.3 Branches
192.4 Compute Endpoints
202.5 Roles and Databases
212.6 The Object Hierarchy in Summary
222.7 Naming Conventions for the Meridian Project
232.8 Practical Considerations for Project Design
24CHAPTER 3
25Provisioning and Initial Configuration
263.1 Prerequisites
273.2 Creating the Project
283.3 Initial PostgreSQL Configuration
293.4 Creating Additional Databases
303.5 Creating Application Roles
313.6 Installing Extensions
323.7 Configuring the Connection Endpoint
333.8 Verifying the Provisioned Environment
34Verify project details
35List branches
36List compute endpoints
37Test connection
38Verify extensions
39Verify databases
403.9 Documenting the Provisioned State
41CHAPTER 4
42Connection Management and Pooling
434.1 The Connection Lifecycle in Neon
444.2 The Neon Connection Pooler
45Direct connection (no pooler):
46Pooled connection:
474.3 Sizing the Connection Pool
484.4 Application-Side Connection Configuration
494.5 Connection Routing and Read Replicas
504.6 Monitoring Connection Usage
51CHAPTER 5
52Branching Strategies for Development and Testing
535.1 The Concept of Database Branching
545.2 Branch Lifecycle Management
555.3 Creating Branches
56Create a branch from the current head of main
57Create a branch from a specific point in time (useful for reproducing issues)
58Create a branch from a specific LSN
595.4 Working with Branches
60Get the connection string for a branch
61Connect using psql
625.5 Resetting Branches
635.6 Branch-per-Pull-Request Strategy
645.7 Branch-per-Test-Suite Strategy
65In CI pipeline setup
66Run tests
67In CI pipeline teardown (always, regardless of test success/failure)
685.8 Data Masking Considerations
695.9 Branch Storage Management
70Delete all branches matching the ci/ prefix that are older than 2 hours
71CHAPTER 6
72Schema Migration Operations
736.1 Migration Tool Compatibility
746.2 Migration Testing on Branches
75Step 1: Create a migration test branch
76Step 2: Get the connection string
77Step 3: Run the migration with timing
78Step 4: Validate
79Step 5: Clean up
806.3 Writing Safe Migrations
816.4 Lock Monitoring During Migrations
826.5 Migration Execution Procedure for Production
83CHAPTER 7
84Autoscaling, Suspension, and Compute Lifecycle
857.1 Compute States
867.2 Auto-Suspend Configuration
87Set auto-suspend to 5 minutes (300 seconds)
88Disable auto-suspend (compute runs continuously)
897.3 Autoscaling Configuration
907.4 Cold Start Optimization
91Simple heartbeat via cron (every 4 minutes for a 5-minute suspend timeout)
927.5 Compute Restart Behavior
93Restart a compute endpoint
947.6 Read Replica Compute Lifecycle
95Create a read replica with auto-suspend enabled
96CHAPTER 8
97Monitoring, Observability, and Alerting
988.1 Neon Console Metrics
998.2 PostgreSQL System Views for Monitoring
1008.3 Key Monitoring Queries
1018.4 Integration with External Monitoring
1028.5 Alerting Thresholds
1038.6 Log Analysis
104CHAPTER 9
105Backup, Recovery, and Point-in-Time Restore
1069.1 How Backup Works in Neon
1079.2 Retention Periods
1089.3 Point-in-Time Restore via Branching
109Restore to a specific timestamp
1109.4 Recovery Procedures
1119.5 Testing Recovery Procedures
1129.6 Logical Backups as Supplementary Protection
1139.7 Retention Policy Documentation
114CHAPTER 10
115Security, Access Control, and Compliance
11610.1 Platform-Level Security
11710.2 Network-Level Security
11810.3 PostgreSQL-Level Security
11910.4 Credential Rotation
12010.5 Audit Logging
12110.6 Compliance Considerations
122CHAPTER 11
123Performance Tuning and Query Optimization
12411.1 The Neon Performance Model
12511.2 Measuring and Improving Cache Hit Rates
12611.3 Index Optimization
12711.4 Query Plan Analysis
12811.5 VACUUM and ANALYZE Configuration
12911.6 Connection-Specific Performance Settings
13011.7 Benchmarking and Load Testing
131Create a benchmark branch
132Run pgbench against the branch
133CHAPTER 12
134Production Runbooks and Incident Response
13512.1 Runbook: High Connection Count
13612.2 Runbook: Slow Query Degradation
13712.3 Runbook: Accidental Data Modification
13812.4 Runbook: Cold Start Latency Spike
13912.5 Runbook: Storage Limit Approaching
140List all branches with their storage consumption
14112.6 Incident Communication Template
142CHAPTER 13
143Multi-Environment Architectures and CI/CD Integration
14413.1 The Meridian Environment Architecture
14513.2 API-Driven Provisioning
14613.3 Terraform Provider
14713.4 CI/CD Pipeline Integration Patterns
148Weekly staging refresh (run via scheduled CI job)
149Run latest migrations against refreshed staging
15013.5 Secret Management
15113.6 Deployment Coordination
152CHAPTER 14
153Cost Management and Capacity Planning
15414.1 Pricing Components
15514.2 Cost Optimization Strategies
156Review compute hour consumption
15714.3 Capacity Planning
15814.4 Budget Alerts
15914.5 Total Cost of Ownership Comparison
160APPENDIX A
161Neon CLI Reference
162Installation
163npm
164Homebrew
165Direct download (Linux)
166Authentication
167Environment variable (preferred for CI/CD)
168Project Commands
169Branch Commands
170Endpoint Commands
171Connection String
172Role Commands
173Database Commands
174Compute Settings
175Global Options
176APPENDIX B
177Neon API Quick Reference
178Common Headers
179Key Endpoints
180Example: Create Branch with Endpoint
181Rate Limits
182APPENDIX C
183PostgreSQL Extension Compatibility Matrix
184BIBLIOGRAPHY AND REFERENCES
185COLOPHON