Installation and API keys

This document will get you started with the very basics of how to authenticate your project against a Xata database. More context on how to use Xata once you've installed it can either be found in the client SDK pages, the API reference pages, or with one of our platform quickstarts.

Install the Xata CLI

Xata comes with a CLI (command line tool) to help connect your project code to xata. It does this by setting up environment variables for your database location and API keys to securely fetch against your data. We recommend installing Xata globally to make this easier.

# Installs the CLI globally
npm install -g @xata.io/cli

You can alternatively install Xata only within your project and manage it through your package manager and scripts.

Authenticate the CLI to your account

The CLI needs to know who is running it. This means authenticating it against our logged in user and generating an API key to use when we push, pull or create any databases we make. To set this up run:

xata auth login

This should open your browser and give a confirmation message. Remember to make sure you are logged in to Xata before performing this step. On completion this command will create a new API key for your user account which you should see in account settings page within the Xata UI. That key will also be stored locally on your computer (the location might vary for each OS). It should look like this:

# .config/xata/credentials
[default]
apiKey=YOUR_API_KEY_HERE

Setting up necessary Xata files in your project

Once you have the CLI globally installed with an API key, you can run xata init inside any project folder to set up project specific files that Xata requires to know which database to connect to. This is done with the xata init command.

# Initialize xata in your project directory
xata init

When run for the first time within a project directory the xata init command will prompt you with questions about how to set up your project. If you've already set up a database using the web application, you can select it and generate code to match.

The xata init command will create three important files in your project that you'll want to become familiar with.

.env

The .env file will contain an API key (auto-generated for you) along with any branch details you may have set up.

# API key used by the CLI and the SDK
# Make sure your framework/tooling loads this file on startup to have it available for the SDK
XATA_API_KEY=YOUR_API_KEY_HERE
XATA_BRANCH=main

If for some reason you lose your API KEY, you can always generate a new one within the account settings page of the web application.

.xatarc

The .xatarc file is located in the root of your project directory and includes the location of your database, as well as the location of where to store generated code (if you optionally chose language codegen during xata init).

1
2
3
4
5
6
{
  "databaseUrl": "https://my-xata-app-database-url"
  "codegen": {
    "output": "src/xata.ts"
  }
}

Generated code and credentials

Depending upon the codegen you went with during xata init the CLI will create a file to store generated client code and typings. When choosing TypeScript the default file location will be the src/xata.ts. Because the content of this file is generated, you shouldn't edit it directly but import and wrap its contents. This can be helpful to pass in the environment variables.

tsx
tsxpython
1
2
3
// This would allow you to wrap the generated client from src/xata.ts with your own credentials
import { XataClient } from './xata.ts'
export const xata = new XataClient({ apiKey: process.env.XATA_API_KEY })

Working with client SDKs

Xata offers a set of client SDKs to help you build your application. The SDKs are available for the following languages:

Trying out the JavaScript SDK within the web application

The Xata web application contains a playground area where you can try out the SDK.

Right now the playground is only available for the JavaScript/TypeScript SDK, but we plan to add support for other languages in the future. This should allow you to try out a couple queries against your live database without needed to work with local code.Be careful when pointing to your main branch as any operations you perform there will be permanent.

Managing API keys

Create new API keys by visiting your account settings page. From here you can also delete or refresh existing keys. If you forget a key, we recommend deleting it and making a new one.