Installation & 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.

Xata comes with a CLI (command line interface) 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.

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

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.

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.

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).

{
  "databaseUrl": "https://my-xata-app-database-url"
  "codegen": {
    "output": "src/xata.ts"
  }
}

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. Often it can be helpful to create a utility file that wraps and exports the client to pass in your environment variables. For example, here is a util file that might be helpful to make.

// 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 })

# Environment variables, like `XATA_API_KEY` are detected from the client
from xata.client import XataClient
client = XataClient()

import (
	"github.com/xata-api/go/xata"
)
func main() {
	// Environment variables, like `XATA_API_KEY`, are detected from the client
	workspaces, _ := xata.NewWorkspacesClient()
}

For collaborative development in a common Workspace it is important to set up your local environment so that it can be replicated by others. Commit these specific files to your project's repository:

• .xata: This folder holds the migration files, managing changes to the database schema over time.
• .xatarc: This file contains essential configuration information for your database setup.
• src/xata.ts: Includes the Xata client and API integration, responsible for interacting with the Xata service from code.

Committing these files to your project's repository, enables Workspace members to replicate your local setup by adding their own XATA_API_KEY to their .env file.

To deploy your GitHub repository on hosting services like Vercel or Netlify, ensure you include the generated src/xata.ts file in your repo. Even if the repository is open source, exposing the src/xata.ts file generally doesn't pose a risk to your database’s limits or security, as long as the API key is a secret. The file does contain the database URL, but requests made without authentication won’t impact your Xata database's rate limits.

When creating templates or examples for public use and cloning, it is best to avoid committing files that have details specific to a database, like API endpoints and client configurations. Configuration files such as src/xata.ts,.xatarc and the .xata migrations folder are linked to a specific database.

To share code in a way that is agnostic to the Xata database and workspace in use, do the following:

1. Export your database schema to schema.json using the command xata schema dump -f schema.json.

2. Avoid sharing src/xata.ts, .xatarc, and .xata which contain endpoint-specific information. Instead, share only the schema.json file.

3. Users can set up their database with your schema configuration using the command xata init --schema schema.json. The command initializes a database using the schema information from your schema.json file. It then generates the src/xata.ts and .xatarc files, along with the .xata folder, for their own specific database setup. This approach prevents the sharing of sensitive configuration files and ensures the confidentiality of your database URL.

In your project's README, you can provide instructions on how to recreate the database with the above step. Additionally, you can also instruct users to import data into their database using CSV files. For more details, refer to the docs on importing CSV data.

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

• TypeScript SDK: type-safe SDK for Node.js, V8 and Deno
• Python SDK: in progress SDK client for Python 3.8
• Go SDK: alpha version SDK for Golang

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.

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.