Amazon Aurora HTTP Client is a solution that adds an HTTP Client for Amazon Aurora MySQL-Compatible Edition and Amazon Aurora PostgreSQL-Compatible Edition. The solution uses the integration of Amazon Aurora and AWS Lambda. For the HTTP Client function, this solution uses the Node.js platform.
The primary use case for Aurora Lambda HTTP Client is to help customers who are looking for an alternative for Oracle UTL_HTTP when migrating from Oracle to Aurora.
Amazon Aurora HTTP Client is implemented as a Node.js Lambda function. Amazon Aurora invokes this function and passes the following input parameters: endpoint URL, request type, request headers, and request body. The Lambda function then makes the HTTP request and sends the HTTP response back to Aurora.
We recommend that you integrate the deployment of this function into your CI/CD pipeline and automate this process with such tools as AWS CDK.
The following example shows the deployment of Aurora Lambda HTTP Client with AWS CLI:
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
# install only production dependencies
npm install --omit=dev
# zip function code and its dependencies
zip -r amazon-aurora-http-client.zip *.js node_modules
# create IAM role and attach policies
aws iam create-role --role-name amazon-aurora-http-client-role --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
aws iam attach-role-policy --role-name amazon-aurora-http-client-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam attach-role-policy --role-name amazon-aurora-http-client-role --policy-arn arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
# create function
aws lambda create-function \
--function-name amazon-aurora-http-client \
--runtime nodejs18.x \
--tracing-config Mode=Active \
--zip-file fileb://amazon-aurora-http-client.zip \
--handler index.handler \
--role arn:aws:iam::${AWS_ACCOUNT_ID}:role/amazon-aurora-http-client-roleAfter you deploy the Lambda function, you can use AWS Lambda Console to test it.
The following code example shows all supported parameters:
{
"url": "https://checkip.amazonaws.com/",
"requestType": "POST",
"headers": {
"Accept-Encoding": "application/json",
"Accept-Language": "en-US,en;q=0.7,es;q=0.3"
},
"body": {
"this": ["is", "a", "test"]
}
}In the preceding example, the headers and body parameters are optional. The following code example shows a simple GET request.
{
"url": "https://checkip.amazonaws.com/",
"requestType": "GET"
}The output of the Lambda function is a JSON object:
{
"statusCode": 200,
"statusMessage": "OK",
"headers": {
"date": "Thu, 10 Nov 2022 08:59:17 GMT",
"content-type": "application/json; charset=utf-8",
"content-length": "134"
},
"body": [
{ "id": 1, "title": "Post 1" },
{ "id": 2, "title": "Post 2" },
{ "id": 3, "title": "Post 3" }
]
}Note: if the response content type is JSON, the
bodyfield is returned as a JSON object, otherwise it is returned as a string.
After Lambda function is deployed, follow Invoking a Lambda function with an Aurora MySQL native function for Aurora MySQL or Invoking an AWS Lambda function from an Aurora PostgreSQL DB cluster for Aurora PostgreSQL, to enable and setup Lambda integration in your cluster.
For Aurora PostgreSQL, run the following code to create a function which invokes the HTTP Client Lambda solution:
-- create required AWS extensions
CREATE EXTENSION IF NOT EXISTS aws_commons;
CREATE EXTENSION IF NOT EXISTS aws_lambda;
CREATE OR REPLACE FUNCTION http_client(IN p_endpoint TEXT, IN p_request_type CHARACTER VARYING(10), IN p_headers JSON, IN p_body TEXT)
RETURNS TEXT
LANGUAGE plpgsql
AS
$BODY$
DECLARE
/* Lambda HTTP Client function name and region */
LAMBDA_NAME CONSTANT CHARACTER VARYING(25) := 'amazon-aurora-http-client';
LAMBDA_REGION CONSTANT CHARACTER VARYING(15) := 'eu-central-1';
/* Request */
request_json JSON;
/* Response */
lambda_response_code INTEGER;
external_endpoint_response_code INTEGER;
lambda_response_payload JSON;
response TEXT;
/* Errors */
lambda_function_error CHARACTER VARYING(20) := 'Lambda Error';
external_endpoint_error CHARACTER VARYING(30) := 'External Endpoint Error';
BEGIN
/* Build the request object */
request_json := json_build_object(
'url', p_endpoint,
'payload', p_body,
'headers', p_headers,
'requestType', p_request_type
);
/* Get the results */
SELECT
status_code,
payload->'statusCode',
payload->'body'::TEXT
INTO
lambda_response_code,
external_endpoint_response_code,
response
FROM aws_lambda.invoke(
aws_commons.create_lambda_function_arn(LAMBDA_NAME, LAMBDA_REGION),
request_json
);
/* Check basic errors */
IF lambda_response_code != 200 THEN
RAISE USING detail = lambda_function_error;
END IF;
IF external_endpoint_response_code IS NOT NULL AND external_endpoint_response_code != 200 THEN
RAISE USING detail = external_endpoint_error;
END IF;
/* Return response to the user */
RETURN response;
END;
$BODY$;
-- example of an invocation of the http_call function
SELECT * FROM http_client(
'https://checkip.amazonaws.com',
'POST',
jsonb_build_object('Content-Type', 'application/x-www-form-urlencoded')::JSON,
'form_encoded_body=example');This project uses AWS X-Ray SDK for Node.js to instrument HTTPS calls. These calls are automatically added to the X-Ray service graph.
For example, if the Amazon Aurora HTTP Client invokes Amazon API Gateway, which invokes other Lambda functions or AWS services, X-Ray captures them as downstream services:
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.