github.com/hashicorp/vault/sdk@v0.13.0/database/dbplugin/README.md (about)

     1  # Combined Database Engine
     2  This package is how database plugins interact with Vault.
     3  
     4  ## Upgrading to Version 5
     5  
     6  ### Background
     7  In Vault 1.6, a new Database interface was created that solved a number of issues with the
     8  previous interface:
     9  
    10  1. It could not use password policies because the database plugins were responsible for
    11     generating passwords.
    12  2. There were significant inconsistencies between functions in the interface.
    13  3. Several functions (`SetCredentials` and `RotateRootCredentials`) were doing the same operation.
    14  4. It had a function that was no longer being used as it had been deprecated in a previous version
    15     but never removed.
    16  
    17  Prior to Vault 1.6, the Database interface is version 4 (with other versions in older versions of
    18  Vault). The new version introduced in Vault 1.6 is version 5. This distinction was not exposed in
    19  previous iterations of the Database interface as the previous versions were additive to the
    20  interface. Since version 5 is an overhaul of the interface, this distinction needed to be made.
    21  
    22  We highly recommend that you upgrade any version 4 database plugins to version 5 as version 4 is
    23  considered deprecated and support for it will be removed in a future release. Version 5 plugins
    24  will not function with Vault prior to Vault 1.6.
    25  
    26  The new interface is roughly modeled after a [gRPC](https://grpc.io/) interface. It has improved
    27  future compatibility by not requiring changes to the interface definition to add additional data
    28  in the requests or responses. It also simplifies the interface by merging several into a single
    29  function call.
    30  
    31  ### Upgrading your custom database
    32  
    33  Vault 1.6 supports both version 4 and version 5 database plugins. The support for version 4
    34  plugins will be removed in a future release. Version 5 database plugins will not function with
    35  Vault prior to version 1.6. If you upgrade your database plugins, ensure that you are only using
    36  Vault 1.6 or later. To determine if a plugin is using version 4 or version 5, the following is a
    37  list of changes in no particular order that you can check against your plugin to determine
    38  the version:
    39  
    40  1. The import path for version 4 is `github.com/hashicorp/vault/sdk/database/dbplugin`
    41     whereas the import path for version 5 is `github.com/hashicorp/vault/sdk/database/dbplugin/v5`
    42  2. Version 4 has the following functions: `Initialize`, `Init`, `CreateUser`, `RenewUser`,
    43     `RevokeUser`, `SetCredentials`, `RotateRootCredentials`, `Type`, and `Close`. You can see the
    44     full function signatures in `sdk/database/dbplugin/plugin.go`.
    45  3. Version 5 has the following functions: `Initialize`, `NewUser`, `UpdateUser`, `DeleteUser`,
    46     `Type`, and `Close`. You can see the full function signatures in
    47     `sdk/database/dbplugin/v5/database.go`.
    48  
    49  If you are using a version 4 custom database plugin, the following are basic instructions
    50  for upgrading to version 5.
    51  
    52  -> In version 4, password generation was the responsibility of the plugin. This is no longer
    53     the case with version 5. Vault is responsible for generating passwords and passing them to
    54     the plugin via `NewUserRequest.Password` and `UpdateUserRequest.Password.NewPassword`.
    55  
    56  1. Change the import path from `github.com/hashicorp/vault/sdk/database/dbplugin` to
    57     `github.com/hashicorp/vault/sdk/database/dbplugin/v5`. The package name is the same, so any
    58     references to `dbplugin` can remain as long as those symbols exist within the new package
    59     (such as the `Serve` function).
    60  2. An easy way to see what functions need to be implemented is to put the following as a
    61     global variable within your package: `var _ dbplugin.Database = (*MyDatabase)(nil)`. This
    62     will fail to compile if the `MyDatabase` type does not adhere to the
    63     `dbplugin.Database` interface.
    64  3. Replace `Init` and `Initialize` with the new `Initialize` function definition. The fields that
    65     `Init` was taking (`config` and `verifyConnection`) are now wrapped into `InitializeRequest`.
    66     The returned `map[string]interface{}` object is now wrapped into `InitializeResponse`.
    67     Only `Initialize` is needed to adhere to the `Database` interface.
    68  4. Update `CreateUser` to `NewUser`. The `NewUserRequest` object contains the username and
    69     password of the user to be created. It also includes a list of statements for creating the
    70     user as well as several other fields that may or may not be applicable. Your custom plugin
    71     should use the password provided in the request, not generate one. If you generate a password
    72     instead, Vault will not know about it and will give the caller the wrong password.
    73  5. `SetCredentials`, `RotateRootCredentials`, and `RenewUser` are combined into `UpdateUser`.
    74     The request object, `UpdateUserRequest` contains three parts: the username to change, a
    75     `ChangePassword` and a `ChangeExpiration` object. When one of the objects is not nil, this
    76     indicates that particular field (password or expiration) needs to change. For instance, if
    77     the `ChangePassword` field is not-nil, the user's password should be changed. This is
    78     equivalent to calling `SetCredentials`. If the `ChangeExpiration` field is not-nil, the
    79     user's expiration date should be changed. This is equivalent to calling `RenewUser`.
    80     Many databases don't need to do anything with the updated expiration.
    81  6. Update `RevokeUser` to `DeleteUser`. This is the simplest change. The username to be
    82     deleted is enclosed in the `DeleteUserRequest` object.
    83