Xata SDK for Python
To install the library enter the following command:
pip install xata
xata package is a standalone SDK library that features
XataClient. By installing the package, you can import the SDK into your Python project and start building on top of Xata.
To bootstrap the SDK we recommend you use the workspace URL. In the Web UI, navigate to Workspaces then Configuration. You will be directed to the workspace API base URL. Copy the URL and use it to configure routing.
The URL can be passed to the client as a parameter:
xata = XataClient(db_url="REDACTED_DB_URL")
Or you can set the environment variable:
XATA_DATABASE_URL. The parameter value will take precedence over the environment variable.
The format of the database URL (
db_url) parameter must follow the format of:
https://test-123456.us-east-1.xata.sh/db/mydb. The branch name is not mandatory, it can be either appended to the URL, with a
: as the separator, like this
https://test-123456.us-east-1.xata.sh/db/mydb:my-feature-branch. Alternatively, you can specify the
branch_name with the parameter in
There are multiple options to pass your Xata credentials to the client. Xata will check the following using this order of precedence:
- Parameters passed to the constructor
- Environment variables
.xatarc file is generated by the Xata CLI in the current directory when running the command
If the previous options were empty, the client looks for a
.env file in the project root directory. Visit the Authentication page to read more about best practices.
.xatarc configuration file is the final source to retrieve the API key and the workspace.
Refer to the authentication page to learn more about the
.xatarc file and best practices.
If no parameters passed, the client probes the following environment variables for authentication.
export XATA_API_KEY="REDACTED_API_KEY" export XATA_DATABASE_URL="REDACTED_DB_URL"
from xata.client import XataClient client = XataClient()
Inject the API key and workspace
id directly into the constructor as a parameter:
from xata.client import XataClient client = XataClient(api_key="REDACTED_API_KEY", db_url="REDACTED_DB_URL")
There are multiple options to point the SDK to a specific branch, if none is selected, the SDK elects
main as current branch name.
The environment variable
XATA_BRANCH can specify a branch, the SDK will look for the variable and initialize the SDK with that value.
You can also, set the branch with the database URL (
db_url) on SDK init, we want to use the branch
feature-042 on the database
Planes, we can initialize the SDK with:
xata = XataClient(db_url="https://test-12345.us-east-1.xata.sh/db/Planes:feature-042")
Another options is to specify the
branch_name in the SDK. If you specify
branch_name, the latter will be ignored.
If you want to change the branch for a single request, you can do so with all workspace endpoints, by setting the
xata.records().insert("Planes", record, branch_name="feature-042")
The SDK builds on the requests package and includes built-in logging support. By configuring the log level to debug, you can view the URL and status code by default.
The API surface of the Python SDK is organized into namespaces, with each namespace associated with a specific set of APIs. For instance, the
databases namespace provides access to all the available Xata endpoints for managing databases.
Alternatively, you can directly instantiate a namespace, as demonstrated in this example.
|Authentication and API key management|
|User invites management|
|Branch schema migrations and history|
|Table records access operations|
|APIs for searching, querying, filtering, and aggregating records|
|Database table management|
The endpoints and namespaces are generated from the OpenAPI specification.