Create a new connection

When creating a new connection to SurrealDB, you can choose to connect to a local or remote endpoint, specify a namespace and database pair to use, authenticate with an existing token, authenticate using a pair of credentials, or use advanced custom logic to prepare the connection to the database.

First, you need to initialize a new instance of the Surreal or AsyncSurreal class and connect it to a database endpoint.

Related Methods and Properties

While the Surreal class is the primary method to connect to SurrealDB, there are other methods that you can use while managing your connection.

Surreal / AsyncSurreal

You can specify your connection protocol either as http, https, ws, or wss.

Example usage

# Connect to a local endpoint with http protocol
db = Surreal('http://127.0.0.1:8000')

# Connect to a remote endpoint with ws protocol
db = AsyncSurreal('wss://cloud.surrealdb.com')

Effect of connection protocol on token & session duration

The connection protocol you choose affects how authentication tokens and sessions work:

With websockets connections (ws://, wss://) you open a single long-lived stateful connection where after the initial authentication, the session duration applies and if not specified, defaults to NONE meaning that the session never expires unless otherwise specified.

When you connect with a HTTP connection (http://, https://), every request you make is short-lived and stateless, requiring you to authenticate every request individually for which the token is used, creating a short lived session. Hence, the token duration which defaults to 1 hour applies.

You can extend the session duration of a token or a session by setting the DURATION clause when creating a new access method with the DEFINE ACCESS METHOD statement or when defining a new user with the DEFINE USER statement.

Learn more about token and session duration in our security best practices documentation.

.use()

Depending on the complexity of your use case, you can switch to a specific namespace and database using the .use() method. This is particularly useful if you want to switch to a different setup after connecting. You can also stay in the same namespace but switch to a different database.

Learn more about the .use() method in the methods section.

Example usage

db.use(namespace='surrealdb', database='docs')

.close()

The .close() method closes the persistent connection to the database. You should call this method when you are done with the connection to free up resources.

Example usage

db.close()

Context manager

You can also use Python’s context manger to automatically open and close a connection when exiting the context.

Putting it all together

from surrealdb import Surreal

# Without using a context manager
db = Surreal('ws://localhost:8000')
db.use('namespace', 'database')
# Sign in and your code...
db.close()

# Using a context manager
with Surreal('ws://localhost:8000') as db:
    db.use('namespace', 'database')
	# Sign in and your code...

The same applies when using Async

from surrealdb import AsyncSurreal

# Without using a context manager
db = AsyncSurreal('ws://localhost:8000')
await db.use('namespace', 'database')
# Sign in and your code...
await db.close()

# Using a context manager
async with AsyncSurreal('ws://localhost:8000') as db:
    await db.use('namespace', 'database')
	# Sign in and your code...