Llamadas a la API de datos de Amazon RDS con la AWS CLI - Amazon Aurora
Inicio de una transacción SQLEjecución de una instrucción SQLEjecución de una instrucción SQL por lotes en una matriz de datosConfirmación de una transacción SQLRestauración de una transacción SQL

Llamadas a la API de datos de Amazon RDS con la AWS CLI

Puede llamar a la API de datos de RDS (API de datos) mediante la AWS CLI.

En los siguientes ejemplos se utiliza la AWS CLI para la API de datos. Para obtener más información, consulte la referencia de AWS CLI de la API de datos.

En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.

nota

La AWS CLI puede dar formato a las respuestas de JSON.

Inicio de una transacción SQL

Puede iniciar una transacción SQL ejecutando el comando de la CLI aws rds-data begin-transaction. La llamada devuelve un identificador de transacción.

importante

Dentro de la API de datos, el tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un periodo de tres minutos. Si una transacción agota su tiempo antes de que se confirme, la API de datos se revertirá automáticamente.

Las instrucciones de lenguaje de definición de datos (DDL) de MySQL dentro de una transacción causan una confirmación implícita. Recomendamos que ejecute cada instrucción DDL de MySQL en un comando execute-statement independiente con la opción --continue-after-timeout.

Además de las opciones comunes, especifique la opción --database, que proporciona el nombre de la base de datos.

Por ejemplo, el comando de la CLI siguiente inicia una transacción SQL.

Para Linux, macOS o Unix:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

Para Windows:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

A continuación se muestra un ejemplo de respuesta.

{
    "transactionId": "ABC1234567890xyz"
}

Ejecución de una instrucción SQL

Puede ejecutar una instrucción SQL usando el comando de la CLI aws rds-data execute-statement.

Puede ejecutar la instrucción SQL en una transacción especificando el identificador de transacción con la opción --transaction-id. Puede iniciar una transacción ejecutando el comando de la CLI aws rds-data begin-transaction. Puede finalizar y confirmar una transacción ejecutando el comando de la CLI aws rds-data commit-transaction.

importante

Si no especifica la opción --transaction-id, los cambios que se generan a partir de la llamada se confirman automáticamente.

Además de las opciones habituales, especifique las opciones siguientes:

  • --sql (obligatorio): instrucción SQL que debe ejecutarse en el clúster de base de datos.

  • --transaction-id (opcional): identificador de una transacción que se inició mediante el comando begin-transaction de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL.

  • --parameters (opcional): parámetros de la instrucción SQL.

  • --include-result-metadata | --no-include-result-metadata (opcional): valor que indica si deben incluirse o no metadatos en los resultados. El valor predeterminado es --no-include-result-metadata.

  • --database (opcional): el nombre de la base de datos.

    Es posible que la opción --database no funcione al ejecutar una instrucción SQL después de ejecutar --sql "use database_name;" en la solicitud anterior. Le recomendamos que utilice la opción --database en lugar de ejecutar instrucciones --sql "use database_name;".

  • --continue-after-timeout | --no-continue-after-timeout (opcional): un valor que indica si se seguirá o no ejecutando la instrucción después de que la llamada supere el intervalo de tiempo de espera de la API de datos de 45 segundos. El valor predeterminado es --no-continue-after-timeout.

    Para las instrucciones en lenguaje de definición de datos (DDL), recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada, a fin de evitar errores y la posibilidad de que las estructuras de datos se dañen.

  • --format-records-as "JSON"|"NONE": valor opcional que especifica si se debe dar formato al conjunto de resultados como cadena JSON. El valor predeterminado es "NONE". Para obtener información sobre el procesamiento de conjuntos de resultados JSON, consulte Procesamiento de resultados de consultas de API de datos de Amazon RDS en formato JSON.

El clúster de base de datos devuelve una respuesta para la llamada.

nota

El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.

Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.

Por ejemplo, el siguiente comando de la CLI ejecuta una única instrucción SQL y omite los metadatos en los resultados (valor predeterminado).

Para Linux, macOS o Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"

Para Windows:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"

A continuación se muestra un ejemplo de respuesta.

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

El siguiente comando de la CLI ejecuta una única instrucción SQL en una transacción mediante la opción --transaction-id.

Para Linux, macOS o Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

Para Windows:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

A continuación se muestra un ejemplo de respuesta.

{
    "numberOfRecordsUpdated": 1
}

El siguiente comando de la CLI ejecuta una única instrucción SQL con parámetros.

Para Linux, macOS o Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

Para Windows:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

A continuación se muestra un ejemplo de respuesta.

{
    "numberOfRecordsUpdated": 1
}

El siguiente comando de la CLI ejecuta una instrucción SQL de lenguaje de definición de datos (DDL). La instrucción DDL cambia el nombre de la columna job por la columna role.

importante

Para las instrucciones DDL, recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, especifique la opción --continue-after-timeout.

Para Linux, macOS o Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

Para Windows:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

A continuación se muestra un ejemplo de respuesta.

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}
nota

Los datos generatedFields no se admiten en Aurora PostgreSQL. Para obtener los valores de los campos generados, utilice la cláusula RETURNING. Para obtener más información, consulte Returning Data From Modified Rows en la documentación de PostgreSQL.

Ejecución de una instrucción SQL por lotes en una matriz de datos

Puede ejecutar una instrucción SQL por lotes en una matriz de datos ejecutando el comando aws rds-data batch-execute-statement de la CLI. Puede utilizar este comando para realizar una operación de actualización o importación masiva.

Puede ejecutar la instrucción SQL en una transacción especificando el identificador de transacción con la opción --transaction-id. Puede iniciar una transacción ejecutando el comando de la CLI aws rds-data begin-transaction. Puede finalizar y confirmar una transacción mediante el comando aws rds-data commit-transaction de la CLI.

importante

Si no especifica la opción --transaction-id, los cambios que se generan a partir de la llamada se confirman automáticamente.

Además de las opciones habituales, especifique las opciones siguientes:

  • --sql (obligatorio): instrucción SQL que debe ejecutarse en el clúster de base de datos.

    sugerencia

    Para las sentencias compatibles con MySQL, no incluya un punto y coma al final del parámetro --sql. Un punto y coma final puede causar un error de sintaxis.

  • --transaction-id (opcional): identificador de una transacción que se inició mediante el comando begin-transaction de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL.

  • --parameter-set (opcional): los conjuntos de parámetros para la operación por lotes.

  • --database (opcional): el nombre de la base de datos.

El clúster de base de datos devuelve una respuesta a la llamada.

nota

No existe un límite máximo fijo en el número de conjuntos de parámetros. Sin embargo, el tamaño máximo de la solicitud HTTP enviada a través de la API de datos es de 4 MiB. Si la solicitud supera este límite, la API de datos devuelve un error y no procesa la solicitud. Este límite de 4 MiB incluye el tamaño de los encabezados HTTP y la notación JSON en la solicitud. Por lo tanto, el número de conjuntos de parámetros que puede incluir depende de una combinación de factores, como el tamaño de la sentencia SQL y el tamaño de cada conjunto de parámetros.

El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.

Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.

Por ejemplo, el siguiente comando de la CLI ejecuta una instrucción SQL por lotes en una matriz de datos con un conjunto de parámetros.

Para Linux, macOS o Unix:

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

Para Windows:

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
nota

No incluya saltos de línea en la opción --parameter-sets.

Confirmación de una transacción SQL

Con el comando aws rds-data commit-transaction de la CLI, puede finalizar una transacción SQL que inició con aws rds-data begin-transaction y confirmar los cambios.

Además de las opciones habituales, especifique la opción siguiente:

  • --transaction-id (obligatorio): identificador de una transacción que se inició ejecutando el comando begin-transaction de la CLI. Especifique el ID de la transacción que desea finalizar y confirmar.

Por ejemplo, el siguiente comando de la CLI finaliza una transacción SQL y confirma los cambios.

Para Linux, macOS o Unix:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Para Windows:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

A continuación se muestra un ejemplo de respuesta.

{
    "transactionStatus": "Transaction Committed"
}

Restauración de una transacción SQL

Con el comando aws rds-data rollback-transaction de la CLI, puede revertir una transacción SQL que inició con aws rds-data begin-transaction. Si revierte una transacción, cancelará sus cambios.

importante

Si el ID de la transacción ha vencido, la transacción se revertirá automáticamente. En este caso, un comando aws rds-data rollback-transaction que especifique el ID de transacción que ha vencido devolverá un error.

Además de las opciones habituales, especifique la opción siguiente:

  • --transaction-id (obligatorio): identificador de una transacción que se inició ejecutando el comando begin-transaction de la CLI. Especifique el ID de la transacción que desea revertir.

Por ejemplo, el comando de la AWS CLI siguiente revierte una transacción SQL.

Para Linux, macOS o Unix:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Para Windows:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

A continuación se muestra un ejemplo de respuesta.

{
    "transactionStatus": "Rollback Complete"
    }