diff --git a/docs/maintenance-mode.mdx b/docs/maintenance-mode.mdx new file mode 100644 index 0000000000..b54a56a799 --- /dev/null +++ b/docs/maintenance-mode.mdx @@ -0,0 +1,14 @@ +--- +title: Maintenance Mode +description: Learn about Clerk's Maintenance Mode. +--- + +Maintenance Mode is a special operational state designed to ensure minimal disruption to signed in users during critical database upgrades or outages. + +{/* TODO: the following sentence might not be worth mentioning: */} + +When enabled, the system becomes aware that the primary database might be unavailable, but it can still operate using the read replica and Redis to process read requests and maintain session-related functionalities. + +Since the majority of requests in production environments are either GET requests or session refresh requests, maintenance mode allows us to serve most users with minimal interruption. + +Mutation methods (POST, PATCH, PUT, DELETE) will be rejected with a `503 Service Unavailable` status and an error message informing users that the system is temporarily unavailable.