{"id":13877795,"url":"https://github.com/graphile/postgraphile-lambda-example","last_synced_at":"2026-01-28T05:19:11.305Z","repository":{"id":42048616,"uuid":"124863871","full_name":"graphile/postgraphile-lambda-example","owner":"graphile","description":"Simple serverless / Lambda example with caching and lightweight bundle","archived":false,"fork":false,"pushed_at":"2024-11-21T20:11:24.000Z","size":812,"stargazers_count":142,"open_issues_count":8,"forks_count":20,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-03T17:13:03.011Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PLpgSQL","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/graphile.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":"2018-03-12T09:20:43.000Z","updated_at":"2025-02-21T20:49:32.000Z","dependencies_parsed_at":"2023-02-08T18:31:40.982Z","dependency_job_id":"26873fbb-e5b6-486e-a156-ba2df2549ff1","html_url":"https://github.com/graphile/postgraphile-lambda-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/graphile/postgraphile-lambda-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fpostgraphile-lambda-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fpostgraphile-lambda-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fpostgraphile-lambda-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fpostgraphile-lambda-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphile","download_url":"https://codeload.github.com/graphile/postgraphile-lambda-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile%2Fpostgraphile-lambda-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28840088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T02:10:51.810Z","status":"ssl_error","status_checked_at":"2026-01-28T02:10:50.806Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":[],"created_at":"2024-08-06T08:01:24.342Z","updated_at":"2026-01-28T05:19:11.283Z","avatar_url":"https://github.com/graphile.png","language":"PLpgSQL","funding_links":[],"categories":["PLpgSQL"],"sub_categories":[],"readme":"# PostGraphile Lambda Example\n\n## Overview\n\nThis project shows an example of how you might use PostGraphile on Lambda. It\nhas the following aims:\n\n- [x] Startup without needing to introspect database\n- [x] Fast startup\n- [x] Small bundle size\n- [x] JWT auth supported OOTB\n- [x] Graphile-build schema plugin support\n- [x] Support for middlewares\n- [x] No requirement for Node.js `http`-based libraries (such as Connect,\n      Express, Koa)\n\n## Non-goals\n\nPostgraphile-lambda-example does NOT intend to watch the schema for changes;\nthis means that you _must_ build and release a new version every time you\nchange your database. (You only need to update the cache file though.)\n\nPostgraphile-lambda-example does NOT intend to make this fully compatible with\nthe `postgraphile` CLI - this will be a subset best suited to Lambda usage.\n\nPostgraphile-lambda-example does NOT intend to support subscriptions.\n\n## Method\n\nWe use the following tools:\n\n- webpack - to bundle up the required code into as small a file as possible\n  (no need for `node_modules` any more!)\n- PostGraphile `writeCache` / `readCache` - we'll introspect the database\n  during the build and write the results to a cache file to be included in the\n  bundle; then when the Lambda service starts up it can read from the cache\n  rather than introspecting the database again.\n- serverless.js (optional) - for automated AWS deployments.\n\n## Setup\n\nFirst clone this repository locally, and install dependencies:\n\n```\nyarn\n```\n\nNext, set up a `.env` file matching your environment:\n\n```\ncp .env.template .env\n```\n\nAnd modify the `src/postgraphileOptions.js` and `serverless.yml` files to your taste.\n\n#### AWS VPC settings\n\nWhen you're deploying Postgraphile using Lambda, you can run your DB instance on AWS as well in order to make use of AWS's integrated security using VPCs. In that case you can restrict the public accessibility of your DB instance from the internet. *If you don't host your DB on AWS you can ignore this section.*\n\nWhen using RDS for example, our use case **requires two ways of access**:\n\n1. The Postgraphile Lambda function we will create needs access to the RDS instance. We achieve that by creating the Lambda function within the same VPC our RDS instance lives in.\n2. In some use cases that's all you need and you can completely hide the RDS from public access and only make it accessible from within the VPC (at a later point in production you might even do it that way). In our case this would be a bit inconvenient because our Postgraphile scripts need to access the DB during schema generation and this process runs on our local machine. Therefore we add the ability to access the DB instance publicly, though restricted to our current IP. (The ability to connect to the DB from our local system is helpful in many other situations as well, e.g. when running migrations or when accessing the database through a DB client.)\n\nAchieving this can be a bit confusing if you're new to VPCs. When you create your RDS instance, set the following \"Network \u0026 Security\" settings:\n\n- VPC \u0026 subnet group: default (RDS instances are always created within a VPC and your AWS account comes with its default VPC)\n- Public accessibility: Yes (this is for our second requirement, but don't expect that this alone will make your RDS instance publicly accessible: access is always regulated through your security group settings and if there is no rule there that allows public access, then setting \"yes\" here does not in any way expose your instance)\n- VPC security groups: We actually need two different security groups. Just select \"Create new VPC security group\" here. Then RDS will automatically create a new security group with an inbound rule of type `PostgresQL` restricted to your current IP address as source. This will satisfy our second requirement. After you created your instance, click on \"Modify\" and return to your security group settings. Now add the `default` security group as the second one. This security group allows other entities within the VPC (e.g. our Lambda function) to access this entity (the RDS instance) which is needed for our first requirement. You might have expected that entities are able to access other entities within the same VPC by default, but you have to add this security group explicitly.\n\nIf you want to learn more, here's some more info on [VPCs in the context of RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_VPC.WorkingWithRDSInstanceinaVPC.html) and on [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html).\n\nNow, we just have to make sure that our Lambda is created within our VPC as well. For that just use the AWS_VPC environment variables from the `.env.template` and add the following to the specifications of your `graphql` function in your `serverless.yml` file:\n\n```\nvpc:\n  securityGroupIds:\n    \"Fn::Split\":\n      - \",\"\n      - ${env:AWS_VPC_SECURITY_GROUP_IDS}\n  subnetIds:\n    \"Fn::Split\":\n      - \",\"\n      - ${env:AWS_VPC_SUBNET_IDS}\n```\n\nYou can find all these values in the RDS console under \"Connectivity \u0026 Security\". (As the securityGroupId it's enough to use the `default` one: this basically makes the Lambda function part of the VPC. There should be 3 subnetIds.)\n\n(You will also need to add `\"iam:AttachRolePolicy\"` to the permissions of the Serverless IAM role policy you will later create.)\n\nHint: Don't forget that your access to RDS from your local computer is based on your current network, so when you want to e.g. re-generate the Postgraphile schema, but are now connected to a different network, you'll have to return to the `rds-launch-wizard` security group settings, edit the inbound rule and select \"My IP\" at source to automatically update your IP.\n\n## Automatic Deployment with Serverless.js\n\nThis repository runs bash scripts during deployment written on Mac which you can find in the `scripts` folder. These scripts should run just fine on Mac and Linux, but you might run into problems on Windows. As a workaround you can just run Linux within Windows and run the deployment scripts there. If you're on Windows 10 you can install a command line Linux distro from the Microsoft Store - there is a guide further below. If you're using another version of Windows, you could run Linux in a VM (or possibly a Docker container).\n\n#### On Mac/Linux\n\n- install [serverless](https://serverless.com/framework/docs/providers/aws/guide/installation/) - `yarn global add serverless`\n- Make sure you configured your [aws credentials](https://serverless.com/framework/docs/providers/aws/guide/credentials/) - if you're doing that for the first time, just create the IAM role and then use the aws-cli method as described in the link (Hint: make sure that the IAM role policy you copied from the gist contains `\"s3:GetBucketLocation\"`)\n\nNow you can deploy to AWS using serverless.js by running:\n\n```\nyarn deploy\n```\n\n#### On Windows 10\n\n- After you completed the steps in [Setup](#setup), go to the Microsoft Marketplace in the start menu and install a command line linux distro of your choice (we use ubuntu 18.04 in these instructions).\n- Run ubuntu and create a user and password.\n- Run `sudo apt update` to get access to the latest packages.\n- Install and activate a virtual environment: Follow the steps in [this tutorial](https://linuxize.com/post/how-to-create-python-virtual-environments-on-ubuntu-18-04/) until after the activation. From now on, always keep running within the virtual environment. (Why we do this: We will use the `aws-cli` to provide serverless with AWS credentials to create the stack on AWS on your behalf. `aws-cli` relies on python3 which is also used by the Linux system, but in a different version. In order to avoid version conflicts/incompatibilites, we install the `aws-cli` in a virtual environment which comes with its own python installation.)\n- Install the aws-cli by running `pip install --upgrade awscli` (from within the venv). You can make sure it installed correctly by running `aws --version`.\n- If you haven't already done that, create an IAM role for serverless as described [here](https://serverless.com/framework/docs/providers/aws/guide/credentials/). (Hint: Make sure that the IAM role policy you copied from the gist contains `\"s3:GetBucketLocation\"`.)\n- Save the credentials to aws-cli by running `aws configure` ([more details](https://serverless.com/framework/docs/providers/aws/guide/credentials#setup-with-the-aws-cli)).\n- Install yarn (you do need to use yarn and not npm because the scripts use yarn) as described on [their website](https://yarnpkg.com/lang/en/docs/install/#debian-stable), serverless with `yarn global add serverless` and zip with `sudo apt-get install zip`.\n- Cd to your postgraphile project folder you created during setup and run `yarn deploy`.\n\n#### After deployment\n\nJust copy the URL that Serverless returns in the command line under `endpoints` after successful deployment and paste it into your GraphQL client of choice - you can now talk to your Lambda PostGraphile API 😅\n\n## Setting up a Lambda endpoint manually\n\nIf you prefer not to use the serverless.js framework, you can also deploy your lambda function manually.\n\nNote 1: Change your process.env.AWS_STAGE_NAME to \"/default\" to match the default stage name for manually deployed API Gateways.\n\nNote 2: CORS is enabled by default. Remove cors() middleware in `/src/index.js` if you would prefer disabled cors.\n\n0. Run `yarn build` to create `lambda.zip` file that you can upload to Amazon Lambda.\n1. Visit https://console.aws.amazon.com/lambda/home and click 'Create function'\n2. Select \"Author from scratch\" and give your function a name, select the most recent Node.js release (at least 8.10+), create (or select) a role (I granted \"Simple microservice permissions\")\n3. Click \"Create function\" and wait about 15 seconds; you should be greeted with a \"Congratulations\" message.\n4. Scroll to \"Function code\", select \"Upload a .zip file\" from \"Code entry type\", press the \"Upload\" button and select the `lambda.zip` file you generated above; then click \"Save\"\n5. Scroll to \"Environment variables\" and enter your `DATABASE_SCHEMAS` and `DATABASE_URL` settings; then click \"Save\"\n6. Scroll to the top and select \"API Gateway\" under \"Add triggers\" in the \"Designer\", then scroll to \"Configure triggers\"\n7. Create a new API; if you like add 'image/gif', 'image/png', 'image/icon' and 'image/x-icon' to the list of binary media types; then press \"Add\" followed by \"Save\"\n8. Click the name of the API gateway to go to the API gateway config\n9. Select the `/` route under `Resources` and from the \"Actions\" dropdown, select \"Create method\" add create an `ANY` method\n10. Turn on \"Lambda Proxy Integration\" and enter your lambda function name in the relevant box, then press \"Save\"\n11. Finally, go to \"Actions\" again and \"Deploy API\"\n12. Copy the \"Invoke URL\" and paste it into your GraphQL client of choice - you can now talk to your Lambda PostGraphile API 😅\n\nIf you want GraphiQL support (STRONGLY DISCOURAGED! Use an external GraphQL\nclient such as GraphiQL.app, Altair or GraphQL Playground instead!), then you\nneed to go back to stage 9, and choose 'Create Resource', tick \"Configure as a\nproxy resource\", press \"Create Resource\" and then configure it with the name of\nyour lambda function, you should also change the settings in\n`src/postgraphileOptions.js` (see comment in that file).\n\n## How it works\n\n### Phases\n\nThe system operates based on a number of phases. Each phase depends on the\nprevious non-optional phase; so if an earlier phase rebuilds then all later\nphases must also rebuild.\n\n#### Phase 1: build postgraphile: `scripts/build`\n\nUses webpack to produce a single JS file containing all that is necessary,\nusing `src/index.js` as the entry point.\n\nCompiles `src/**` to `dist/`\n\n**Start here when**: you change your code, add/remove plugins, or upgrade dependencies.\n\n#### Phase 2: generate cache: `scripts/generate-cache`\n\nUses a similar approach to `postgraphile --write-cache` to write a cache file\ncontaining introspection details of your database.\n\nGenerates `dist/postgraphile.cache`\n\n**Start here when**: database schema changes.\n\n#### Phase 3: bundle: `scripts/bundle`\n\nProduce a zip file combining the two artifacts above - `dist/index.js` and `dist/postgraphile.cache`.\n\nGenerates `lambda.zip` from `dist/` folder\n\n#### Phase 4 (optional): test: `scripts/test`\n\nLaunch the bundle in the `sam local` test environment, and run a series of requests.\n\n**Manual checking of the results is required.**\n\n#### Phase 5: upload to Lambda\n\nLeft as an exercise to the reader.\n\n### Test Prerequisites\n\n- [docker](https://docs.docker.com/install/)\n- [aws sam cli](https://docs.aws.amazon.com/lambda/latest/dg/sam-cli-requirements.html) - `pip install aws-sam-cli`\n\n### Running tests\n\nInstall dependencies\n\n```\nyarn\n```\n\nCopy .env.template to .env and customize as you like:\n\n```\ncp .env.template .env\n```\n\nIf you're using the default `.env.template` file then you'll need to populate the\n`postgraphile_forum_example` database:\n\n```\n./scripts/import-example-database\n```\n\nMake sure that the query in `test/query.graphql` and the options in `src/postgraphileOptions.js` are both valid for your database. If you're using a remote PostgreSQL server (or one within a docker instance), you may need to update the `host.docker.internal` reference in `test/make-template-yml.sh` (line 15).\n\nRun the tests:\n\n```\nyarn test\n```\n\nNote the first run might take a while whilst the system installs the relevant\ndocker images.\n\nIn the test output you should see a number of `0 error(s)` statements, and some successful GraphQL HTTP request payloads\n\n### Running local sam instance\n\nDo the same as for the test, but instead of running `yarn test` at the end, instead run:\n\n```\nyarn sam\n```\n\nThis will set up a local GraphQL endpoint at http://127.0.0.1:3000/graphql\n\nYou can then use a GraphQL client such as Altair or GraphQL Playground to issue requests.\n\nIf you're using the sample database then you can generate a JWT via:\n\n```graphql\nmutation {\n  authenticate(input: { email: \"spowell0@noaa.gov\", password: \"iFbWWlc\" }) {\n    jwtToken\n  }\n}\n```\n\n([Other users exist](https://github.com/graphile/postgraphile/blob/160670dd91ca7faddf784351b33da2bb9924df39/examples/forum/data.sql#L18-L27).)\n\nThen set the JWT header:\n\n```json\n{\n  \"Authorization\": \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZm9ydW1fZXhhbXBsZV9wZXJzb24iLCJwZXJzb25faWQiOjEsImlhdCI6MTUzODEyOTEyMSwiZXhwIjoxNTM4MjE1NTIxLCJhdWQiOiJwb3N0Z3JhcGhpbGUiLCJpc3MiOiJwb3N0Z3JhcGhpbGUifQ.NFZ10gvIB29VL1p3Wh-Cc74JSigOOhgtqaMCP9ZA2W0\"\n}\n```\n\nThen you can issue an authenticated query:\n\n```graphql\n{\n  currentPerson {\n    nodeId\n    id\n    fullName\n  }\n}\n```\n\nNote that SAM unpacks the zip and reboots node for every single request, so you're going to suffer some startup latency with this.\n\n### Troubleshooting\n\n- If you receive serverless errors during `yarn deploy`, sometimes they can be resolved by just running the command another time. At the time of writing (20/Mar/2019), there is also a temporal error with Serverless v1.39: \"Can't find graphql.zip file\". If this happens downgrade to Serverless 1.38 by running `yarn global add serverless@1.38`.\n- If your serverless stack is created successfully, but then your endpoint throws some unhelpful errors, check the Cloudwatch logs of the Lambda. If you notice that the Lambda just times out, you might try checking the security settings of your DB instance. For example, if you use RDS with the \"public\" setting enabled, the public access might be restricted to your IP address. This would result in the schema being successfully generated during stack creation from your device, but the Lambda not having access obviously (without any error messages hinting you in that direction). You can quick-fix that by setting the inbound settings of the security group of the RDS instance to all IPs (or even better by [making the Lambda access RDS from within the VCP](#aws-vpc-settings))\n- If you want to remove your stack from AWS and you try running `serverless remove`, you may run into errors. If that happens, you can go to Cloudformation in the AWS console and delete your stack there.\n\n### Related Projects\n\nA PostGraphile lambda example using [Zeit now.sh](https://zeit.co/) to manage\nthe deployment: https://github.com/ggascoigne/now-postgraphile\n\n### Thanks\n\nImprovements to PostGraphile's support for Lambda were sponsored by [Connecting Good](https://cogo.co/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile%2Fpostgraphile-lambda-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphile%2Fpostgraphile-lambda-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile%2Fpostgraphile-lambda-example/lists"}