yandex-cloud/ydb-php-sdk

YDB PHP SDK

维护者

详细信息

github.com/ydb-platform/ydb-php-sdk

源代码

问题

安装数: 21,321

依赖关系: 0

建议者: 0

安全: 0

星标: 26

关注者: 12

分支: 15

开放问题: 23

v1.15.0 2024-04-16 09:46 UTC

Requires

Requires (Dev)

Apache-2.0 c1d820748601cd4bb9e028d3ffa2922501b20f6a

  • Alexei Shabalin <mail.woop@alshabalin.com>

This package is auto-updated.

Last update: 2024-09-18 09:28:12 UTC

README

YDB PHP SDK 提供了从 PHP 代码访问 YDB 的功能。

YDB 是一个开源的分布式容错数据库管理系统，具有高可用性和可扩展性，严格的一致性和 ACID。查询使用 SQL 方言 - YQL。

YDB 可在几种模式下使用

  • 本地安装（本 SDK 目前不支持）；
  • YC 中的无服务器计算模式（只有执行的操作才收费）；
  • YC 中的专用实例模式（专用计算资源收费）。

文档

https://ydb.tech/docs/

安装

推荐使用 Composer 进行安装。

运行以下命令

composer require ydb-platform/ydb-php-sdk

连接

首先，使用 Yandex Cloud 控制台 创建数据库。

YDB 支持以下身份验证方法

  • 访问令牌
  • OAuth 令牌
  • JWT + 私钥
  • JWT + JSON 文件
  • 元数据 URL
  • 匿名

访问令牌

使用您的访问令牌

<?php

use YdbPlatform\Ydb\Ydb;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)

        // Access token authentication
        'access_token'    => 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\AccessTokenAuthentication;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)
    ],
    
    'credentials' => new AccessTokenAuthentication('AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')
];

$ydb = new Ydb($config);

OAuth 令牌

您应该获取 新的 OAuth 令牌。

使用您的 OAuth 令牌

<?php

use YdbPlatform\Ydb\Ydb;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'temp_dir'       => './tmp', // Temp directory
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)

        // OAuth token authentication
        'oauth_token'    => 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\OAuthTokenAuthentication;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'temp_dir'       => './tmp', // Temp directory
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)
    ],
    
    'credentials' => new OAuthTokenAuthentication('AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')
];

$ydb = new Ydb($config);

JWT + 私钥

创建具有 editor 角色的 服务帐户，然后创建私钥。您还需要密钥 ID 和服务帐户 ID。

连接到您的数据库

<?php

use YdbPlatform\Ydb\Ydb;

$config = [
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',
    'discovery'   => false,
    'iam_config'  => [
        'temp_dir'           => './tmp', // Temp directory
        'root_cert_file'     => './CA.pem', // Root CA file (dedicated server only!)

        // Private key authentication
        'key_id'             => 'ajexxxxxxxxx',
        'service_account_id' => 'ajeyyyyyyyyy',
        'private_key_file'   => './private.key',
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\JwtWithPrivateKeyAuthentication;

$config = [
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',
    'discovery'   => false,
    'iam_config'  => [
        'temp_dir'           => './tmp', // Temp directory
        'root_cert_file'     => './CA.pem', // Root CA file (dedicated server only!)

        // Private key authentication
        'key_id'             => 'ajexxxxxxxxx',
        'service_account_id' => 'ajeyyyyyyyyy',
        'private_key_file'   => './private.key',
    ],
    
    'credentials' => new JwtWithPrivateKeyAuthentication(
        "ajexxxxxxxxx","ajeyyyyyyyyy",'./private.key')
        
];

$ydb = new Ydb($config);

JWT + JSON 文件

创建具有 editor 角色的 服务帐户。

创建服务帐户 JSON 文件，将其保存为您的项目中的 sa_name.json。

连接到您的数据库

<?php

use YdbPlatform\Ydb\Ydb;

$config = [
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',
    'discovery'   => false,
    'iam_config'  => [
        'temp_dir'       => './tmp', // Temp directory
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)

        // Service account JSON file authentication
        'service_file'   => './sa_name.json',
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\JwtWithJsonAuthentication;

$config = [
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',
    'discovery'   => false,
    'iam_config'  => [
        'temp_dir'       => './tmp', // Temp directory
        'root_cert_file' => './CA.pem', // Root CA file (dedicated server only!)
    ],
            
    'credentials' => new JwtWithJsonAuthentication('./jwtjson.json')
];

$ydb = new Ydb($config);

元数据 URL

当您将项目部署到 Yandex.Cloud 的虚拟机或函数时，您可以使用 元数据 URL 连接到数据库。在开始之前，您应将服务帐户链接到现有或新的虚拟机或函数。

<?php

use YdbPlatform\Ydb\Ydb;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'temp_dir'     => './tmp', // Temp directory
        'use_metadata' => true,
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\MetadataAuthentication;

$config = [

    // Database path
    'database'    => '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',

    // Database endpoint
    'endpoint'    => 'ydb.serverless.yandexcloud.net:2135',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'temp_dir'     => './tmp', // Temp directory
    ],
    'credentials' => new MetadataAuthentication()
];

$ydb = new Ydb($config);

匿名

<?php

use YdbPlatform\Ydb\Ydb;

$config = [

    // Database path
    'database'    => '/local',

    // Database endpoint
    'endpoint'    => 'localhost:2136',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'anonymous' => true,
        'insecure' => true,
    ],
];

$ydb = new Ydb($config);

或

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\AnonymousAuthentication;

$config = [

    // Database path
    'database'    => '/local',

    // Database endpoint
    'endpoint'    => 'localhost:2136',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'insecure' => true,
    ],
    
    'credentials' => new AnonymousAuthentication()
];

$ydb = new Ydb($config);

由环境变量确定

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\EnvironCredentials;

$config = [

    // Database path
    'database'    => '/local',

    // Database endpoint
    'endpoint'    => 'localhost:2136',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'insecure' => true,
    ],
    
    'credentials' => new EnvironCredentials()
];

$ydb = new Ydb($config);

以下算法适用于 YDB-PHP-SDK

  1. 如果设置了环境变量 YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS 的值，则使用 系统帐户密钥 身份验证模式，并从该变量指定的文件中获取密钥。
  2. 否则，如果环境变量 YDB_ANONYMOUS_CREDENTIALS 的值设置为 1，则使用匿名身份验证模式。
  3. 否则，如果环境变量 YDB_METADATA_CREDENTIALS 的值设置为 1，则使用 元数据 身份验证模式。
  4. 否则，如果环境变量 YDB_ACCESS_TOKEN_CREDENTIALS 的值设置，则使用 访问令牌 身份验证模式，其中此变量的值被传递。
  5. 否则，使用 元数据 身份验证模式。

静态凭证

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\Implement\StaticAuthentication;

$config = [

    // Database path
    'database'    => '/local',

    // Database endpoint
    'endpoint'    => 'localhost:2136',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'insecure' => true,
    ],
    
    'credentials' => new StaticAuthentication($user, $password)
];

$ydb = new Ydb($config);

从文本文件读取

<?php

use YdbPlatform\Ydb\Ydb;
use YdbPlatform\Ydb\Auth\ReadTokenFromFile;

$config = [

    // Database path
    'database'    => '/local',

    // Database endpoint
    'endpoint'    => 'localhost:2136',

    // Auto discovery (dedicated server only)
    'discovery'   => false,

    // IAM config
    'iam_config'  => [
        'insecure' => true,
    ],
    
    'credentials' => new ReadTokenFromFile($tokenPath, $refreshTime)
];

$ydb = new Ydb($config);

用法

您应该从表服务初始化会话以开始带重试的查询。

<?php

use YdbPlatform\Ydb\Ydb;

$config = [
    // ...
];

$ydb = new Ydb($config);

// obtaining the Table service
$table = $ydb->table();

$result = $table->retryTransaction(function(Session $session){
    // making a query
    return $session->query('select * from `users` limit 10;');
}, true);

$users_count = $result->rowCount();
$users = $result->rows();

$columns = $result->columns();

一旦您的脚本完成，会话将被销毁。

自定义查询

通常，通过 query() 方法进行常规查询就足够了，但在特殊情况下，您可能需要微调查询设置。您可以使用查询构建器来实现。

<?php

$result = $table->retryTransaction(function(Session $session){

    // creating a new query builder instance
    $query = $session->newQuery('select * from `users` limit 10;');
    
    // a setting to keep in cache
    $query->keepInCache();
    
    // a setting to begin a transaction with the given mode
    $query->beginTx('stale');
    
    return $query->execute();
}, true);

查询构建器的方法

  • keepInCache(bool $value) - 是否保留在缓存中（默认：true）
  • collectStats(int $value) - 收集统计信息（默认：1）
  • parameters(array $parameters) - 参数
  • operationParams(\Ydb\Operations\OperationParams $operation_params) - 操作参数
  • beginTx(string $mode) - 以指定 模式 开启事务
    • stale
    • online
    • online_inconsistent
    • serializable
    • snapshot
  • txControl(\Ydb\Table\TransactionControl $tx_control) - 带有自定义设置的交易控制

您可以通过链式调用这些方法来方便地使用。

日志记录

为了进行日志记录，您需要使用实现了 \Psr\Log\LoggerInterface 的类。YDB-PHP-SDK 在 YdbPlatform\Ydb\Logger 命名空间中内置了日志记录器。

  • NullLogger - 默认
  • SimpleStdLogger($level) - 将日志推送到 STDERR 的日志记录器。

使用示例

$config = [
    'logger' => new \YdbPlatform\Ydb\Logger\SimpleStdLogger(\YdbPlatform\Ydb\Logger\SimpleStdLogger::INFO)
]
$ydb = new \YdbPlatform\Ydb\Ydb($config);

gRPC

gRPC 客户端选项

您可以通过在配置数组中设置选项来自定义 gRPC 客户端的操作。

使用示例

$config = [
    // ...
    'grpc' => [
        'opts' => [
            'grpc.max_receive_message_length' => 8*1024*1024,
            'grpc.default_compression_algorithm' => 2,
            'grpc.default_compression_level' => 2,
        ],
    ],
];
$ydb = new \YdbPlatform\Ydb\Ydb($config);