Importación del controlador Crear una instancia del controlador Operaciones CRUD Trabajo con Amazon Ion

Controlador Amazon QLDB para Go: referencia de un libro de cocina

Esta guía de referencia muestra los casos de uso más comunes del controlador Amazon QLDB para Go. Ofrece ejemplos de código Go que muestran cómo usar operaciones básicas de creación, lectura, actualización y eliminación (CRUD, por sus siglas en inglés). También incluye ejemplos de código para procesar datos de Amazon Ion. Además, esta guía destaca las mejores prácticas para hacer que las transacciones sean idempotentes e implementar restricciones de exclusividad.

nota

Cuando corresponda, algunos casos de uso tienen diferentes ejemplos de código para cada versión principal compatible del controlador QLDB para Go.

Contenido

Importación del controlador

El siguiente ejemplo de código importa el controlador y otrosAWS paquetes necesarios.

nota

En este ejemplo también se importa el paquete Amazon Ion (amzn/ion-go/ion). Necesita este paquete para procesar los datos de Ion al ejecutar algunas operaciones de datos en esta referencia. Para obtener más información, consulte Trabajo con Amazon Ion.

Crear una instancia del controlador

El siguiente ejemplo de código crea una instancia del controlador que se conecta a un nombre de registro especificado en un registro especificadoRegión de AWS.

Operaciones CRUD

QLDB ejecuta operaciones de creación, lectura, actualización y eliminación (CRUD, por sus siglas en inglés) como parte de una transacción.

aviso

Como práctica recomendada, haga que sus operaciones de escritura sean estrictamente idempotentes.

Hacer que las transacciones sean idempotentes

Le recomendamos que haga que las transacciones de escritura sean idempotentes para evitar efectos secundarios inesperados en caso de reintentos. Una transacción es idempotente si puede ejecutarse varias veces y producir resultados idénticos cada vez.

Por ejemplo, considere una transacción que inserta un documento en una tabla denominadaPerson. La transacción debe comprobar primero si el documento ya existe o no en la tabla. Sin esta comprobación, la tabla podría terminar con documentos duplicados.

Supongamos que QLDB confirma correctamente la transacción en el lado del servidor, pero el cliente agota el tiempo de espera mientras espera una respuesta. Si la transacción no es idempotente, podría insertarse el mismo documento más de una vez en caso de reintentarlo.

Uso de índices para evitar escaneos completos de tablas

También se recomienda ejecutar sentencias con una cláusula deWHERE predicado mediante un operador de igualdad en un campo indexado o un identificador de documento; por ejemplo,WHERE indexedField = 123 oWHERE indexedField IN (456, 789). Sin esta búsqueda indexada, QLDB necesita realizar un escaneo de tablas, lo que puede provocar tiempos de espera de las transacciones o conflictos optimistas en el control de concurrencia (OCC).

Para obtener más información sobre la clase OCC, consulteModelo de simultaneidad de Amazon QLDB.

Transacciones creadas implícitamente

La función QLDBDriver.execute acepta una función lambda que recibe una instancia de Transaction, que puede utilizar para ejecutar sentencias. La instancia deTransaction envuelve una transacción creada implícitamente.

Puede ejecutar sentencias dentro de la función lambda mediante laTransaction.Execute función. El controlador confirma implícitamente la transacción cuando la función lambda retorna.

En las siguientes secciones se muestra cómo ejecutar operaciones CRUD básicas, especificar una lógica de reintento personalizada e implementar restricciones de exclusividad.

Contenido

Creación de tablas


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("CREATE TABLE Person")
})

Crear índice


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("CREATE INDEX ON Person(GovId)")
})

Lectura de documentos


var decodedResult map[string]interface{}

// Assumes that Person table has documents as follows:
// { "GovId": "TOYENC486FH", "FirstName": "Brent" }
_, err = driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  result, err := txn.Execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'")
  if err != nil {
    return nil, err
  }
  for result.Next(txn) {
    ionBinary := result.GetCurrentData()
    err = ion.Unmarshal(ionBinary, &decodedResult)
    if err != nil {
      return nil, err
    }
    fmt.Println(decodedResult) // prints map[GovId: TOYENC486FH FirstName:Brent]
  }
  if result.Err() != nil {
    return nil, result.Err()
  }
  return nil, nil
})
if err != nil {
  panic(err)
}

Uso de parámetros de la consulta

El siguiente ejemplo de código usa un parámetro de consulta de tipo nativo.


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("SELECT * FROM Person WHERE GovId = ?", "TOYENC486FH")
})
if err != nil {
  panic(err)
}

El siguiente ejemplo de código utiliza varios parámetros de consulta.


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", "TOYENC486FH", "Brent")
})
if err != nil {
  panic(err)
}

El siguiente ejemplo de código usa una lista de parámetros de consulta.


govIDs := []string{}{"TOYENC486FH", "ROEE1", "YH844"}

result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("SELECT * FROM Person WHERE GovId IN (?,?,?)", govIDs...)
})
if err != nil {
  panic(err)
}

nota

Cuando se ejecuta una consulta sin una búsqueda indexada, se invoca un análisis completo de la tabla. En este ejemplo, se recomienda tener un índice en elGovId campo para optimizar el rendimiento. Si no hay un índice activadoGovId, las consultas pueden tener más latencia y también provocar excepciones de conflictos en la OCC o tiempos de espera en las transacciones.

Inserción de documentos

En el siguiente ejemplo de código se insertan tipos de datos nativos.


_, err = driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  // Check if a document with a GovId of TOYENC486FH exists
  // This is critical to make this transaction idempotent
  result, err := txn.Execute("SELECT * FROM Person WHERE GovId = ?", "TOYENC486FH")
  if err != nil {
    return nil, err
  }
  // Check if there are any results
  if result.Next(txn) {
    // Document already exists, no need to insert
  } else {
    person := map[string]interface{}{
      "GovId": "TOYENC486FH",
      "FirstName": "Brent",
    }
    _, err = txn.Execute("INSERT INTO Person ?", person)
    if err != nil {
      return nil, err
    }
  }
  return nil, nil
})

Esta transacción inserta un documento en laPerson tabla. Antes de insertarlo, primero comprueba si el documento ya existe en la tabla. Esta comprobación hace que la transacción sea de naturaleza idempotente. Incluso si realizas esta transacción varias veces, no causará ningún efecto secundario no deseado.

nota

En este ejemplo, se recomienda tener un índice en elGovId campo para optimizar el rendimiento. Sin un índice activadoGovId, las declaraciones pueden tener más latencia y también provocar excepciones de conflictos en la OCC o tiempos de espera en las transacciones.

Inserción de varios documentos en una declaración

Para insertar varios documentos mediante una solaINSERT sentencia, puede pasar un parámetro de tipo lista a la sentencia de la siguiente manera.


// people is a list
txn.Execute("INSERT INTO People ?", people)

No se incluye el marcador de posición de la variable (?) entre corchetes de doble ángulo (<<...>>) al pasar una lista. En las instrucciones manuales de PartiQL, los corchetes de doble ángulo indican una colección desordenada conocida como bolsa.

Actualización de documentos

El siguiente ejemplo de código usa tipos de datos nativos.


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", "John", "TOYENC486FH")
})

nota

Eliminar documentos

El siguiente ejemplo de código usa tipos de datos nativos.


result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  return txn.Execute("DELETE FROM Person WHERE GovId = ?", "TOYENC486FH")
})

nota

Ejecución de varios estados de cuenta en una transacción


// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
func InsureCar(driver *qldbdriver.QLDBDriver, vin string) (bool, error) {
    insured, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {

        result, err := txn.Execute(
            "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)
        if err != nil {
            return false, err
        }

        hasNext := result.Next(txn)
        if !hasNext && result.Err() != nil {
            return false, result.Err()
        }

        if hasNext {
            _, err = txn.Execute(
                "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin)
            if err != nil {
                return false, err
            }
            return true, nil
        }
        return false, nil
    })
    if err != nil {
        panic(err)
    }

    return insured.(bool), err
}

Lógica de reintento

LaExecute función del controlador tiene un mecanismo de reintento integrado que reintenta la transacción si se produce una excepción que se pueda volver a intentar (como tiempos de espera o conflictos de OCC). Se puede configurar el número máximo de reintentos y la estrategia de reintentos.

El límite de reintentos predeterminado es4, y la estrategia de retroceso predeterminada es ExponentialBackoffStrategycon una base de10 milisegundos. Puede establecer la política de reintentos por instancia de conductor y también por transacción mediante una instancia de RetryPolicy.

El siguiente ejemplo de código especifica la lógica de reintentos con un límite de reintentos personalizado y una estrategia de retroceso personalizada para una instancia del controlador.


import (
  "github.com/aws/aws-sdk-go/aws"
  "github.com/aws/aws-sdk-go/aws/session"
  "github.com/aws/aws-sdk-go/service/qldbsession"
  "github.com/awslabs/amazon-qldb-driver-go/v2/qldbdriver"
)

func main() {
  awsSession := session.Must(session.NewSession(aws.NewConfig().WithRegion("us-east-1")))
  qldbSession := qldbsession.New(awsSession)

  // Configuring retry limit to 2
  retryPolicy := qldbdriver.RetryPolicy{MaxRetryLimit: 2}

  driver, err := qldbdriver.New("test-ledger", qldbSession, func(options *qldbdriver.DriverOptions) {
    options.RetryPolicy = retryPolicy
  })
  if err != nil {
    panic(err)
  }

  // Configuring an exponential backoff strategy with base of 20 milliseconds
  retryPolicy = qldbdriver.RetryPolicy{
    MaxRetryLimit: 2,
    Backoff: qldbdriver.ExponentialBackoffStrategy{SleepBase: 20, SleepCap: 4000,
    }}

  driver, err = qldbdriver.New("test-ledger", qldbSession, func(options *qldbdriver.DriverOptions) {
    options.RetryPolicy = retryPolicy
  })
  if err != nil {
    panic(err)
  }
}

El siguiente ejemplo de código especifica la lógica de reintentos con un límite de reintentos personalizado y una estrategia de retroceso personalizada para una función anónima determinada. LaSetRetryPolicy función anula la política de reintentos establecida para la instancia del controlador.


import (
  "context"
  "github.com/aws/aws-sdk-go/aws"
  "github.com/aws/aws-sdk-go/aws/session"
  "github.com/aws/aws-sdk-go/service/qldbsession"
  "github.com/awslabs/amazon-qldb-driver-go/v2/qldbdriver"
)

func main() {
  awsSession := session.Must(session.NewSession(aws.NewConfig().WithRegion("us-east-1")))
  qldbSession := qldbsession.New(awsSession)

  // Configuring retry limit to 2
  retryPolicy1 := qldbdriver.RetryPolicy{MaxRetryLimit: 2}

  driver, err := qldbdriver.New("test-ledger", qldbSession, func(options *qldbdriver.DriverOptions) {
    options.RetryPolicy = retryPolicy1
  })
  if err != nil {
    panic(err)
  }

  // Configuring an exponential backoff strategy with base of 20 milliseconds
  retryPolicy2 := qldbdriver.RetryPolicy{
    MaxRetryLimit: 2,
    Backoff: qldbdriver.ExponentialBackoffStrategy{SleepBase: 20, SleepCap: 4000,
    }}

  // Overrides the retry policy set by the driver instance
  driver.SetRetryPolicy(retryPolicy2)

  driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
    return txn.Execute("CREATE TABLE Person")
  })
}

Implementación de restricciones de la unicidad

QLDB no admite índices únicos, pero puede implementar este comportamiento en su aplicación.

Supongamos que desea implementar una restricción de exclusividad en elGovId campo de laPerson tabla. Para ello, puede escribir una transacción que haga lo siguiente:

Afirme que la tabla no tiene ningún documento existente con un valor especificadoGovId.
Inserte el documento si se aprueba la afirmación.

Si una transacción competidora aprueba simultáneamente la afirmación, solo una de las transacciones se confirmará correctamente. La otra transacción fallará si se produce una excepción de conflicto de OCC.

En el ejemplo de código siguiente se muestra cómo implementar esta lógica de restricción de unicidad.


govID := "TOYENC486FH"

document := map[string]interface{}{
  "GovId":     "TOYENC486FH",
  "FirstName": "Brent",
}

result, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {
  // Check if doc with GovId = govID exists
  result, err := txn.Execute("SELECT * FROM Person WHERE GovId = ?", govID)
  if err != nil {
    return nil, err
  }
  // Check if there are any results
  if result.Next(txn) {
    // Document already exists, no need to insert
    return nil, nil
  }
  return txn.Execute("INSERT INTO Person ?", document)
})
if err != nil {
  panic(err)
}

nota

Trabajo con Amazon Ion

Las siguientes secciones muestran cómo usar el módulo Amazon Ion para procesar datos de Ion.

Contenido

Importación del módulo Ion


import "github.com/amzn/ion-go/ion"

Crear tipos de Ion

La biblioteca Ion para Go actualmente no admite el modelo de objetos de documento (DOM), por lo que no puedes crear tipos de datos de Ion. Pero puede ordenar y desordenar entre los tipos nativos de Go y los binarios de Ion cuando trabaja con QLDB.

Obtener el binario de Ion


aDict := map[string]interface{}{
  "GovId": "TOYENC486FH",
  "FirstName": "Brent",
}

ionBytes, err := ion.MarshalBinary(aDict)
if err != nil {
  panic(err)
}

fmt.Println(ionBytes) // prints [224 1 0 234 238 151 129 131 222 147 135 190 144 133 71 111 118 73 100 137 70 105 114 115 116 78 97 109 101 222 148 138 139 84 79 89 69 78 67 52 56 54 70 72 139 133 66 114 101 110 116]

Obtener el texto de Ion


aDict := map[string]interface{}{
  "GovId": "TOYENC486FH",
  "FirstName": "Brent",
}

ionBytes, err := ion.MarshalText(aDict)
if err != nil {
  panic(err)
}

fmt.Println(string(ionBytes)) // prints {FirstName:"Brent",GovId:"TOYENC486FH"}

Para obtener más información sobre Ion, consulte la documentación de Amazon Ion en GitHub. Para obtener más ejemplos de código sobre cómo trabajar con Ion en QLDB, consulteTrabajando con tipos de datos de Amazon Ion en Amazon QLDB.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Tutorial de inicio rápido

Node.js controlador