107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
---
|
|
slug: /client
|
|
---
|
|
|
|
# Client
|
|
|
|
The `Client` class is used to connect to a database in either embedded mode or server mode. It automatically selects the appropriate connection mode based on the provided parameters.
|
|
|
|
:::tip
|
|
OceanBase Database is a fully self-developed, enterprise-level, native distributed database developed by OceanBase. It achieves financial-grade high availability on ordinary hardware and sets a new standard for automatic, lossless disaster recovery across five IDCs in three regions. It also sets a new benchmark in the TPC-C benchmark test, with a single cluster size exceeding 1,500 nodes. OceanBase Database is cloud-native, highly consistent, and highly compatible with Oracle and MySQL. For more information about OceanBase Database, see [OceanBase Database](https://www.oceanbase.com/docs/oceanbase-database-cn).
|
|
:::
|
|
|
|
## Connect to an embedded seekdb instance
|
|
|
|
Use the `Client` class to connect to a local embedded seekdb instance.
|
|
|
|
```python
|
|
import pyseekdb
|
|
|
|
# Create embedded client
|
|
client = pyseekdb.Client(
|
|
#path="./seekdb", # Path to SeekDB data directory
|
|
#database="test" # Database name
|
|
)
|
|
```
|
|
|
|
The following table describes the parameters.
|
|
|
|
| Parameter | Value type | Required | Description | Example value |
|
|
| --- | --- | --- | --- | --- |
|
|
| `path` | string | No | The path to the seekdb data directory. seekdb stores database files in this directory and loads them when it starts. | `./seekdb` |
|
|
| `database` | string | No | The name of the database. | `test` |
|
|
|
|
## Connect to a remote server
|
|
|
|
Use the `Client` class to connect to a remote server, which runs seekdb or OceanBase Database.
|
|
|
|
:::tip
|
|
|
|
Before you connect to a remote server, make sure that you have deployed a server instance of seekdb or OceanBase Database. <br/>For information about how to deploy a server instance of seekdb, see [Overview](../../../400.guides/400.deploy/50.deploy-overview.md).<br/>For information about how to deploy OceanBase Database, see [Overview](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000003976427).
|
|
|
|
:::
|
|
|
|
Example: Connect to a server instance of seekdb
|
|
|
|
```python
|
|
import pyseekdb
|
|
|
|
# Create remote server client (SeekDB Server)
|
|
client = pyseekdb.Client(
|
|
host="127.0.0.1", # Server host
|
|
port=2881, # Server port
|
|
database="test", # Database name
|
|
user="root", # Username
|
|
password="" # Password (can be retrieved from SEEKDB_PASSWORD environment variable)
|
|
)
|
|
```
|
|
|
|
The following table describes the parameters.
|
|
|
|
| Parameter | Value type | Required | Description | Example value |
|
|
| --- | --- | --- | --- | --- |
|
|
| `host` | string | Yes | The IP address of the server where the instance is located. | `127.0.0.1` |
|
|
| `prot` | string | Yes | The port number of the instance. The default value is 2881. | `2881` |
|
|
| `database` | string | Yes | The name of the database. | `test` |
|
|
| `user` | string | Yes | The username. The default value is root. | `root` |
|
|
| `password` | string | Yes | The password corresponding to the user. If you do not provide the `password` parameter or specify an empty string, the system retrieves the password from the `SEEKDB_PASSWORD` environment variable. ||
|
|
|
|
Example: Connect to OceanBase Database
|
|
|
|
```python
|
|
import pyseekdb
|
|
|
|
# Create remote server client (OceanBase Server)
|
|
client = pyseekdb.Client(
|
|
host="127.0.0.1", # Server host
|
|
port=2881, # Server port (default: 2881)
|
|
tenant="test", # Tenant name
|
|
database="test", # Database name
|
|
user="root", # Username (default: "root")
|
|
password="" # Password (can be retrieved from SEEKDB_PASSWORD environment variable)
|
|
)
|
|
```
|
|
|
|
The following table describes the parameters.
|
|
|
|
| Parameter | Value type | Required | Description | Example value |
|
|
| --- | --- | --- | --- | --- |
|
|
| `host` | string | Yes | The IP address of the server where the database is located. | `127.0.0.1` |
|
|
| `prot` | string | Yes | The port number of OceanBase Database. The default value is 2881. | `2881` |
|
|
| `tenant` | string | No | The name of the tenant. This parameter is not required for seekdb. For OceanBase Database, the default value is sys. | `test` |
|
|
| `database` | string | Yes | The name of the database. | `test` |
|
|
| `user` | string | Yes | The username corresponding to the tenant. The default value is root. | `root` |
|
|
| `password` | string | Yes | The password corresponding to the user. If you do not provide the `password` parameter or specify an empty string, the system retrieves the password from the `SEEKDB_PASSWORD` environment variable. ||
|
|
|
|
## APIs supported when you use the Client class to connect to a database
|
|
|
|
When you use the `Client` class to connect to a database, you can call the following APIs.
|
|
|
|
| API | Description | Document link |
|
|
| --- | --- | --- |
|
|
| `create_collection()` | Creates a new collection. | [Document](200.collection/100.create-collection-of-api.md) |
|
|
| `get_collection()` | Queries a specified collection. |[Document](200.collection/200.get-collection-of-api.md)|
|
|
| `delete_collection()` | Deletes a specified collection. |[Document](200.collection/400.delete-collection-of-api.md)|
|
|
| `list_collections()` | Lists all collections in the current database.|[Document](200.collection/300.list-collection-of-api.md)|
|
|
| `get_or_create_collection()` | Queries a specified collection. If the collection does not exist, it is created.|[Document](200.collection/250.get-or-create-collection-of-api.md)|
|
|
| `count_collection()` | Queries the number of collections in the current database. |[Document](200.collection/350.count-collection-of-api.md)| |